Skip to main content

Recommendations API

Get intelligent product recommendations with a simple API call.

Quick Start​

curl -X POST "https://api.useadmesh.com/recommend" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best CRM for startups", "format": "auto"}'
📋 Basic Request Format

Endpoint: POST https://api.useadmesh.com/recommend

Required Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Basic Request:

{
  "query": "best CRM for startups",
  "format": "auto"
}
⚙️ Advanced Parameters (Optional)
{
  "query": "best CRM for startups",
  "format": "auto",
  "previous_query": "project management tools",
  "previous_summary": "We discussed project management solutions",
  "session_id": "user_session_123",
  "is_fallback_allowed": true
}

Response Format​

📄 Example Response
{
  "response": {
    "recommendations": [
      {
        "title": "HubSpot CRM",
        "reason": "Perfect for startups with excellent free tier",
        "admesh_link": "https://useadmesh.com/track?ad_id=hubspot-123",
        "pricing": "Free tier available, paid plans from $45/month",
        "features": ["Contact Management", "Deal Tracking", "Email Integration"],
        "has_free_tier": true,
        "trial_days": 14
      }
    ]
  }
}
📊 Complete Response Structure
{
  "session_id": "sess_1703123456_abc123",
  "intent": {
    "categories": ["crm", "software"],
    "goal": "Find the best CRM solution for startups",
    "llm_intent_confidence_score": 0.89
  },
  "response": {
    "summary": "Here are CRM tools that match your goal",
    "recommendations": [
      {
        "title": "HubSpot CRM",
        "reason": "Perfect for startups with excellent free tier",
        "intent_match_score": 0.92,
        "admesh_link": "https://useadmesh.com/track?ad_id=hubspot-123",
        "ad_id": "hubspot-123",
        "product_id": "hubspot-crm",
        "url": "https://hubspot.com",
        "description": "Free CRM with powerful features for small businesses",
        "pricing": "Free tier available, paid plans from $45/month",
        "trial_days": 14,
        "features": ["Contact Management", "Deal Tracking", "Email Integration"],
        "categories": ["crm", "sales"],
        "keywords": ["crm", "sales", "marketing"],
        "has_free_tier": true,
        "offer_trust_score": 0.95,
        "brand_trust_score": 0.92,
        "is_fallback": false
      }
    ],
    "is_fallback": false,
    "recommendation_source": "admesh"
  },
  "tokens_used": 500,
  "model_used": "mistralai/mistral-7b-instruct",
  "recommendation_id": "rec_uuid_123"
}
🔧 Request Parameters Reference
ParameterTypeRequiredDescription
querystring✅User's search query or question
formatstring❌Format type: auto (default), product, conversation
previous_querystring❌Previous query in conversation
session_idstring❌Session identifier for tracking
is_fallback_allowedboolean❌Allow fallback recommendations (default: true)

Code Examples​

🟨 JavaScript
const getRecommendations = async (query) => {
  const response = await fetch('https://api.useadmesh.com/recommend', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, format: 'auto' })
  });

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  const data = await response.json();
  return data.response.recommendations;
};

// Usage
const recommendations = await getRecommendations('best CRM for startups');
🐍 Python
import requests

def get_recommendations(query):
    response = requests.post(
        'https://api.useadmesh.com/recommend',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        json={'query': query, 'format': 'auto'}
    )

    response.raise_for_status()
    data = response.json()
    return data['response']['recommendations']

# Usage
recommendations = get_recommendations('best CRM for startups')
🐘 PHP
<?php
function getRecommendations($query) {
    $data = json_encode(['query' => $query, 'format' => 'auto']);

    $context = stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => [
                'Authorization: Bearer YOUR_API_KEY',
                'Content-Type: application/json'
            ],
            'content' => $data
        ]
    ]);

    $response = file_get_contents('https://api.useadmesh.com/recommend', false, $context);
    $result = json_decode($response, true);
    return $result['response']['recommendations'];
}

// Usage
$recommendations = getRecommendations('best CRM for startups');
?>
⚠️ Error Handling

Common Error Responses:

  • 400 Bad Request: {"detail": "Low intent confidence"}
  • 401 Unauthorized: {"detail": "Invalid API key"}
  • 500 Server Error: {"detail": "Failed to detect intent from query"}

JavaScript Error Handling:

try {
  const recommendations = await getRecommendations(query);
} catch (error) {
  console.error('Failed to get recommendations:', error.message);
  return []; // Return empty array as fallback
}

What You Get​

Each recommendation includes:

  • title - Product/service name
  • reason - Why it's recommended
  • admesh_link - Tracking URL (use this for clicks)
  • pricing - Cost information
  • features - Key features list
📋 Complete Field Reference

Core Fields (Always Present):

  • title, reason, intent_match_score, admesh_link, ad_id, product_id

Optional Fields:

  • url, description, pricing, features, categories, keywords
  • has_free_tier, trial_days, offer_trust_score, brand_trust_score

Next Steps​