Skip to main content
Once you have a valid session, call the /agent/recommend endpoint.
export async function getAdmeshRecommendations(query: string) {
  const ADMESH_BASE = "https://api.useadmesh.com";
  const sessionId =
    localStorage.getItem("admesh_session_id") || (await createAdmeshSession());

  const res = await fetch(`${ADMESH_BASE}/agent/recommend`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.REACT_APP_ADMESH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ 
      query, 
      session_id: sessionId, 
      message_id: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
      format: "auto" 
    }),
  });

  if (res.status === 401) {
    const newSession = await createAdmeshSession();
    return getAdmeshRecommendations(query);
  }

  return res.json();
}

Request Parameters

ParameterTypeRequiredDescription
querystringYesUser’s search or chat query
session_idstringYesSession ID from /agent/session/new
message_idstringYesUnique message ID for deduplication across platforms. Format: msg_{timestamp}_{random}
formatstringNoLayout format: auto, card, inline. Defaults to auto
sourcestringNoSource of the request: "admesh_ui_sdk" (frontend SDK) or "admesh_weave_node" (backend weave integration). Defaults to "admesh_ui_sdk"
Important: message_id is required for deduplication. Generate a unique ID for each message in the format: msg_{timestamp}_{random_string}. This ensures recommendations are not duplicated across multiple requests for the same message.

Example Response

The response follows the finalized minimal schema structure:
{
  "session_id": "admesh_sess_1760022990_w8RkKA",
  "message_id": "msg_1760022990_abc123",
  "recommendations": [
    {
      "product_id": "prod_123",
      "ad_id": "ad_7a2b",
      "recommendation_id": "rec_xyz789",
      "product_title": "Notion for Teams",
      "tail_summary": "Notion is a powerful workspace tool designed for teams...",
      "product_summary": "All-in-one workspace for notes, docs, and collaboration",
      "weave_summary": "Recommended for collaboration and team productivity",
      "exposure_url": "https://api.useadmesh.com/expose/ad_7a2b?...",
      "click_url": "https://api.useadmesh.com/click/r/ad_7a2b?...",
      "product_logo": {
        "url": "https://cdn.example.com/notion-logo.png"
      },
      "categories": ["productivity", "collaboration"],
      "contextual_relevance_score": 0.87,
      "trust_score": 85.5,
      "model_used": "openai/gpt-4o",
      "creative_input": {
        "brand_name": "Notion",
        "product_name": "Notion for Teams",
        "short_description": "All-in-one workspace for notes, docs, and collaboration",
        "long_description": "Notion is a powerful workspace tool designed for teams who need to organize their work, collaborate effectively, and stay productive.",
        "value_props": [
          "Unified workspace",
          "Real-time collaboration",
          "Customizable templates"
        ],
        "context_snippet": "For teams needing better organization and collaboration",
        "cta_label": "Start Free Trial",
        "cta_url": "https://notion.so/signup",
        "assets": {
          "logo_url": "https://cdn.example.com/notion-logo.png",
          "image_urls": ["https://cdn.example.com/notion-screenshot.png"],
          "resource_urls": ["https://notion.so/signup"]
        },
        "offer_summary": "Special offer: 50% off first year for teams"
      }
    }
  ]
}

Response Schema

Top-Level Fields

FieldTypeRequiredDescription
session_idstringYesSession ID from the request
message_idstringYesMessage ID from the request (for deduplication)
recommendationsarrayYesArray of recommendation objects

Recommendation Object (14 Core Fields)

Each recommendation object contains the following fields:
FieldTypeRequiredDescription
product_idstringYesUnique product identifier
ad_idstringYesUnique ad identifier
recommendation_idstringYesUnique recommendation identifier
product_titlestringYesProduct name (renamed from title)
tail_summarystringNoTail format summary text (moved from top-level)
product_summarystringNoProduct summary text (moved from top-level)
weave_summarystringNoWeave format summary for inline integration
exposure_urlstringYesURL to fire when ad is viewed (MRC-compliant)
click_urlstringYesURL to redirect to when ad is clicked
product_logoobjectNoProduct logo object with url field
categoriesarrayNoProduct categories
contextual_relevance_scorenumberNoRelevance score (0.0-1.0)
trust_scorenumberNoTrust score (0-100)
model_usedstringNoAI model used for generation
creative_inputobjectNoFull creative input structure (see below)

Creative Input Object (Optional)

The creative_input object contains detailed creative information:
FieldTypeRequiredDescription
brand_namestringYesBrand or advertiser name
product_namestringYesProduct or offer name
short_descriptionstringYes1-2 sentence summary (max 200 chars)
long_descriptionstringYes2-4 sentence description (max 500 chars)
value_propsarrayYesValue propositions (bullet points)
context_snippetstringYes60-100 character contextual hint for weave format
cta_labelstringYesCall-to-action label
cta_urlstringYesCall-to-action URL
assetsobjectYesCreative assets (logo, images, resource URLs)
offer_summarystringNoSpecial offer summary (when available)
product_idstringNoProduct identifier
categoriesarrayNoProduct categories
fallback_formatsarrayNoFallback ad formats if preferred unavailable

Next → Weave Inline Recommendations