Authentication

All embed APIs require authentication using API keys. This guide covers authentication methods for each API service.

Getting Your API Key

Get your API key from the embed Console. Your console API key starts with mbd- and works across all embed services.

Studio API

Base URL: https://api.mbd.xyz/v3/studio

The Studio API is the recommended way to build custom feed pipelines. It provides composable building-block services — Search, Features, Scoring, Ranking, and Stories — with full control over every stage.

Authentication Method

Include your console API key in the Authorization header using the Bearer scheme:

Authorization: Bearer mbd-{your-api-key}

The same console API key works across all Studio endpoints.

Endpoints

Service	Endpoint	Description
Search	`POST /search/filter_and_sort`	Structured search with filters and sorting
Search	`POST /search/boost`	Relevance-tuned search with boost filters
Search	`POST /search/semantic`	Embedding-based similarity search
Search	`GET /search/frequent_values/{index}/{field}`	Discover available field values
Features	`POST /features/v1`	Enrich items with ML-computed features
Scoring	`POST /scoring/ranking_model/{model}`	Rerank items using trained ML models
Ranking	`POST /ranking/feed`	Sort, diversify, and limit the final feed
Stories	`POST /stories/generate`	Generate personalized narrative content

Example

Search for trending Polymarket prediction markets:

curl -X POST "https://api.mbd.xyz/v3/studio/search/filter_and_sort" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "polymarket-items",
    "size": 25,
    "sort_by": { "field": "volume_24hr", "order": "desc" },
    "include": [
      { "filter": "term", "field": "active", "value": true },
      { "filter": "numeric", "field": "liquidity_num", "operator": ">=", "value": 10000 }
    ]
  }'

Enrich results with personalization features for a wallet:

curl -X POST "https://api.mbd.xyz/v3/studio/features/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "index": "polymarket-wallets",
      "id": "0xf68a281980f8c13828e84e147e3822381d6e5b1b"
    },
    "items": [
      { "index": "polymarket-items", "id": "1289113" }
    ]
  }'

Code Examples

JavaScript/Node.js:

const MBD_BASE = "https://api.mbd.xyz/v3/studio";
const API_KEY = process.env.MBD_API_KEY; // your mbd- key

const response = await fetch(`${MBD_BASE}/search/filter_and_sort`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    index: "polymarket-items",
    size: 25,
    sort_by: { field: "volume_24hr", order: "desc" },
    include: [
      { filter: "term", field: "active", value: true },
      { filter: "numeric", field: "liquidity_num", operator: ">=", value: 10000 },
    ],
  }),
});

const data = await response.json();
console.log(data.result.hits);

Python:

import requests
import os

MBD_BASE = "https://api.mbd.xyz/v3/studio"
API_KEY = os.environ["MBD_API_KEY"]  # your mbd- key

response = requests.post(
    f"{MBD_BASE}/search/filter_and_sort",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "index": "polymarket-items",
        "size": 25,
        "sort_by": {"field": "volume_24hr", "order": "desc"},
        "include": [
            {"filter": "term", "field": "active", "value": True},
            {"filter": "numeric", "field": "liquidity_num", "operator": ">=", "value": 10000},
        ],
    },
)

data = response.json()
print(data["result"]["hits"])

Feed Deployment API

Base URL: https://api.mbd.xyz/v3

The Feed Deployment API provides a high-level endpoint for getting personalized feed recommendations using pre-configured feeds. Supports Polymarket, Farcaster, and Zora content.

Authentication Method

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer mbd-{your-api-key}

Example

Get personalized Polymarket recommendations using a wallet address:

curl -X POST "https://api.mbd.xyz/v3/for-you" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_22952",
    "wallet_address": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
    "top_k": 25,
    "return_metadata": true
  }'

Code Examples

JavaScript/Node.js:

const response = await fetch(
  "https://api.mbd.xyz/v3/for-you",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MBD_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feed_id: "feed_22952",
      wallet_address: "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
      top_k: 25,
      return_metadata: true,
    }),
  }
);

Python:

import requests
import os

response = requests.post(
    "https://api.mbd.xyz/v3/for-you",
    headers={
        "Authorization": f"Bearer {os.environ['MBD_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "feed_id": "feed_22952",
        "wallet_address": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
        "top_k": 25,
        "return_metadata": True,
    },
)

Note: For full control over filtering, scoring, and ranking, use the Studio API instead. The Feed Deployment API is ideal for quick integrations using pre-configured feeds.

Feed Management API

Base URL: https://console-api-us-west-2.mbd.xyz

The Feed Management API lets you create and manage feed configurations. It uses Basic authentication.

Authentication Method

Authorization: Basic mbd-{your-api-key}

Example

curl -X POST "https://console-api-us-west-2.mbd.xyz/api/feed/config" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Polymarket Trending",
    "endpoint": "casts/feed/for-you",
    "status": "active",
    "visibility": "private",
    "config": {
      "candidate_source": "polymarket-items",
      "candidate_source_type": "posts"
    }
  }'

Error Responses

All APIs return standard HTTP status codes for authentication errors:

401 Unauthorized

Returned when:

The API key is missing
The API key is invalid or expired
The authentication format is incorrect

Example Response:

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

Common Issues

Missing Authorization Header — Ensure the Authorization header is included in all requests
Incorrect Authentication Format:
- Studio API: Bearer mbd-{key}
- Feed Deployment API: Bearer mbd-{key}
- Feed Management API: Basic mbd-{key}
Invalid API Key — Verify your key at console.mbd.xyz
Wrong Base URL:
- Studio API: https://api.mbd.xyz/v3/studio
- Feed Deployment API: https://api.mbd.xyz/v3
- Feed Management API: https://console-api-us-west-2.mbd.xyz

Security Best Practices

Never commit API keys to version control — Store keys in environment variables or a secrets manager
Use environment variables:
```
export MBD_API_KEY="mbd-your-key-here"
```
Rotate API keys regularly — Generate new keys periodically and revoke old ones
Use HTTPS only — All embed APIs require HTTPS. Never send keys over unencrypted connections
Use different keys per environment — Separate keys for development, staging, and production

Quick Reference

API	Base URL	Auth Format	Header
Studio	`https://api.mbd.xyz/v3/studio`	Bearer	`Authorization: Bearer mbd-{key}`
Feed Deployment	`https://api.mbd.xyz/v3`	Bearer	`Authorization: Bearer mbd-{key}`
Feed Management	`https://console-api-us-west-2.mbd.xyz`	Basic	`Authorization: Basic mbd-{key}`

Support

For authentication issues or questions:

Check your API key at console.mbd.xyz
Contact support: [email protected]