Deployment

Feed Deployment API Documentation

Simple guide to getting personalized feed recommendations for your users.

Overview

The Feed Deployment API returns personalized content recommendations for users. You provide a feed_id (a pre-configured feed) and a user identifier, and the API returns a ranked list of posts the user is most likely to interact with.

Base URL: https://api.mbd.xyz/v2/farcaster

Authentication: Bearer token (see Authentication Documentation)

Endpoint

POST `/casts/feed/for-you`

Get personalized feed recommendations for a user.

Request

Headers

Authorization: Bearer mbd-{your-api-key}
Content-Type: application/json

Request Body

{
  "feed_id": "feed_390",
  "user_id": "16085",
  "top_k": 25,
  "return_metadata": true,
  "impression_count": 1
}

Parameters

Parameter	Type	Required	Description
`feed_id`	string	✅ Yes	Feed configuration ID (e.g., `"feed_390"`)
`user_id`	string	⚠️ Conditional	Farcaster ID (FID) of the user. Required if `wallet_address` is not provided.
`wallet_address`	string	⚠️ Conditional	Wallet address (verified on Farcaster). Required if `user_id` is not provided. Ignored if `user_id` is specified.
`top_k`	integer	❌ No	Maximum number of posts to return (1-500, default: 25)
`return_metadata`	boolean	❌ No	Include full post metadata (default: false)
`impression_count`	integer	❌ No	Number of posts considered as "seen" by the user (default: 0)

Note: You must provide either user_id or wallet_address (but not both). If both are provided, user_id takes precedence.

Response

Success Response (200)

{
  "status_code": 200,
  "body": [
    {
      "item_id": "0x07cb7745d02cbdfc8bc31207870f0e623aa75573",
      "popular_score": 0.11901387774133333,
      "trending_score": 0.19252691666666666,
      "affinity_score": 0.0,
      "score": 0.11901387774133333,
      "adjusted_score": 0.0011292917029457927,
      "source_feed": "main:feed_390",
      "social_proof": [
        {
          "user_id": 361635,
          "timestamp": 1764865269,
          "interaction": "like"
        }
      ],
      "metadata": {
        "text": "All 3 massively underrated in their genres",
        "author": {
          "user_id": 2,
          "username": "v",
          "display_name": "Varun Srinivasan",
          "pfp_url": "https://..."
        },
        "likes_count": 95,
        "comments_count": 20,
        "shares_count": 8
      }
    }
  ]
}

Response Fields

Each item in the body array contains:

Field	Type	Description
`item_id`	string	Unique post identifier (hash)
`popular_score`	number	Popularity score (0-1)
`trending_score`	number	Trending signal score (0-1)
`affinity_score`	number	User affinity score based on following graph
`interest_score`	number	Interest score based on user's past interactions (may be omitted)
`score`	number	Final combined recommendation score
`adjusted_score`	number	Score adjusted by time decay and other factors
`text_length`	integer	Length of post text in characters
`source_feed`	string	Feed source identifier (e.g., `"main:feed_390"`, `"fallback_main_1:feed_406"`)
`social_proof`	array	Users in viewer's network who interacted with this post
`metadata`	object	Full post details (only included if `return_metadata: true`)

Metadata Object (when return_metadata: true):

Field	Type	Description
`text`	string	Post content
`embed_items`	array	Embedded media URLs
`timestamp`	integer	Unix timestamp when post was created
`author`	object	Author information (user_id, username, display_name, pfp_url)
`likes_count`	integer	Number of likes
`comments_count`	integer	Number of comments
`shares_count`	integer	Number of shares
`ai_labels`	object	AI-detected labels (topics, sentiment, emotion, moderation, web3_topics)
`geo_location`	string	Geographic location (latitude,longitude)
`app_fid`	string	FID of the app that created the post

Examples

Basic Request (User ID)

curl -X POST "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you" \
  -H "Authorization: Bearer mbd-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_390",
    "user_id": "16085",
    "top_k": 25
  }'

Request with Metadata

curl -X POST "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you" \
  -H "Authorization: Bearer mbd-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_390",
    "user_id": "16085",
    "top_k": 25,
    "return_metadata": true
  }'

Request with Wallet Address

curl -X POST "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you" \
  -H "Authorization: Bearer mbd-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_390",
    "wallet_address": "0x1234567890123456789012345678901234567890",
    "top_k": 10,
    "return_metadata": true
  }'

Request with Impression Tracking

curl -X POST "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you" \
  -H "Authorization: Bearer mbd-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_390",
    "user_id": "16085",
    "top_k": 25,
    "impression_count": 5
  }'

JavaScript Example

const response = await fetch(
  "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mbd-your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feed_id: "feed_390",
      user_id: "16085",
      top_k: 25,
      return_metadata: true,
    }),
  }
);

const data = await response.json();
const feed = data.body;

feed.forEach((item) => {
  console.log(`Post: ${item.metadata?.text}`);
  console.log(`Score: ${item.score}`);
  console.log(`Author: ${item.metadata?.author.display_name}`);
});

Python Example

import requests

url = "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you"
headers = {
    "Authorization": "Bearer mbd-your-api-key",
    "Content-Type": "application/json"
}
payload = {
    "feed_id": "feed_390",
    "user_id": "16085",
    "top_k": 25,
    "return_metadata": True
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

for item in data["body"]:
    print(f"Post: {item['metadata']['text']}")
    print(f"Score: {item['score']}")
    print(f"Author: {item['metadata']['author']['display_name']}")

Available Feed IDs

Use these pre-configured feed templates:

Feed ID	Name
`feed_390`	For You
`feed_624`	Zora Feed
`feed_625`	Short Form Video
`feed_626`	Miniapps
`feed_627`	New York
`feed_628`	Coinbase Wallet Creators
`feed_629`	Warpcast Creators

You can also use custom feed IDs created through the Feed Management API.

Error Responses

400 Bad Request

Invalid feed_id:

{
  "status_code": 400,
  "body": "Invalid feed_id for this API"
}

Missing required parameter:

{
  "error": "invalid_request",
  "message": "The feed_id parameter is required",
  "code": 400
}

401 Unauthorized

{
  "error": "AuthenticationError",
  "message": "Invalid or expired API key. Please check your credentials at console.mbd.xyz",
  "code": 401
}

500 Internal Server Error

{
  "error": "InternalServerError",
  "message": "An unexpected error occurred while processing your request. Please try again later.",
  "code": 500
}

Common Use Cases

1. Get Feed for a User

{
  "feed_id": "feed_390",
  "user_id": "16085",
  "top_k": 25
}

2. Get Feed with Full Metadata

{
  "feed_id": "feed_390",
  "user_id": "16085",
  "top_k": 25,
  "return_metadata": true
}

3. Track Impressions

{
  "feed_id": "feed_390",
  "user_id": "16085",
  "top_k": 25,
  "impression_count": 5
}

When you set impression_count to 5, the first 5 items in the response are marked as "seen" and won't appear in future requests for that user.

4. Use Different Feed Templates

{
  "feed_id": "feed_625",
  "user_id": "16085",
  "top_k": 10
}

Use feed_625 for short-form video content, feed_624 for Zora content, etc.

Understanding the Response

Scores

Each post has multiple scores:

score - Final recommendation score (higher = more relevant)
popular_score - How popular the post is
trending_score - How trending the post is
affinity_score - How relevant based on user's following graph
interest_score - How relevant based on user's past interactions
adjusted_score - Score after time decay adjustments

Social Proof

The social_proof array shows which users in the viewer's network have interacted with the post:

"social_proof": [
  {
    "user_id": 361635,
    "timestamp": 1764865269,
    "interaction": "like"
  }
]

Source Feed

The source_feed field tells you where the post came from:

"main:feed_390" - From the main feed
"fallback_main_1:feed_406" - From the first fallback feed
"promotion:video_content" - From a promotion feed