Authentication

Simple API key authentication for AdMesh recommendations API.

Overview

AdMesh uses API key authentication for all requests. Get your API key from the AdMesh Dashboard and include it in your requests.

Quick Authentication

HTTP Header (Recommended)

Include your API key in the Authorization header:

POST /recommend
Host: api.useadmesh.com
Authorization: Bearer admesh_prod_abc123xyz789
Content-Type: application/json

Query Parameter (Testing Only)

For testing, you can include the API key as a query parameter:

POST /recommend?api_key=admesh_prod_abc123xyz789
Host: api.useadmesh.com

Security Warning

Never use query parameters for API keys in production. They can be logged in server logs and browser history.

Direct API Integration

JavaScript/Node.js

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

  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 admesh_prod_abc123xyz789',
            'Content-Type': 'application/json'
        },
        json={
            'query': query,
            'format': 'auto'
        }
    )

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

# Usage
recommendations = get_recommendations('best CRM for startups')

Frontend Integration with UI SDK

The UI SDK displays recommendations fetched from your backend:

// Backend API route (Next.js example)
// pages/api/recommendations.js
export default async function handler(req, res) {
  const { query } = req.body;

  const response = await fetch('https://api.useadmesh.com/recommend', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ADMESH_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, format: 'auto' })
  });

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

// Frontend component
import { AdMeshLayout } from 'admesh-ui-sdk';

function MyComponent() {
  const [recommendations, setRecommendations] = useState([]);

  const fetchRecommendations = async (query) => {
    const response = await fetch('/api/recommendations', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query })
    });
    const recs = await response.json();
    setRecommendations(recs);
  };

  return (
    <AdMeshLayout
      recommendations={recommendations}
      layout="auto"
      onRecommendationClick={(adId, admeshLink) => window.open(admeshLink)}
    />
  );
}

Environment Setup

Use different API keys for different environments:

Development

# .env file
ADMESH_API_KEY=admesh_dev_abc123xyz789
ADMESH_BASE_URL=https://api.useadmesh.com

Production

# .env file
ADMESH_API_KEY=admesh_prod_ghi789rst345
ADMESH_BASE_URL=https://api.useadmesh.com

Environment Variables in Code

// JavaScript/Node.js
const apiKey = process.env.ADMESH_API_KEY;
const baseUrl = process.env.ADMESH_BASE_URL || 'https://api.useadmesh.com';

const response = await fetch(`${baseUrl}/recommend`, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

# Python
import os

api_key = os.environ.get('ADMESH_API_KEY')
base_url = os.environ.get('ADMESH_BASE_URL', 'https://api.useadmesh.com')

response = requests.post(
    f'{base_url}/recommend',
    headers={'Authorization': f'Bearer {api_key}'}
)

API Key Permissions

All AdMesh API keys provide access to:

Get Recommendations - Core recommendation engine
Click Tracking - Automatic click tracking via admesh_link URLs
Analytics - View performance metrics in dashboard

info

AdMesh uses a simplified permission model. All API keys have the same permissions for the recommendation endpoint.

Testing Your API Key

# Test with cURL
curl -X POST "https://api.useadmesh.com/recommend" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "test query", "format": "auto"}'

Error Responses

Invalid API Key

HTTP Status: 401 Unauthorized

{
  "detail": "Invalid API key"
}

Common causes:

Typo in API key
API key has been revoked
Using wrong environment key

Missing API Key

HTTP Status: 401 Unauthorized

{
  "detail": "Authorization header required"
}

Invalid Request Format

HTTP Status: 400 Bad Request

{
  "detail": "Low intent confidence"
}

Server Error

HTTP Status: 500 Internal Server Error

{
  "detail": "Failed to detect intent from query"
}

Error Handling in Code

JavaScript

const getRecommendations = async (query) => {
  try {
    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) {
      const error = await response.json();
      throw new Error(`API Error (${response.status}): ${error.detail}`);
    }

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

Python

import requests

def get_recommendations(query):
    try:
        response = requests.post(
            'https://api.useadmesh.com/recommend',
            headers={
                'Authorization': 'Bearer your_api_key',
                'Content-Type': 'application/json'
            },
            json={'query': query, 'format': 'auto'}
        )

        response.raise_for_status()  # Raises exception for 4xx/5xx status codes

        data = response.json()
        return data['response']['recommendations']
    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error: {e.response.status_code} - {e.response.text}")
        return []
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return []

Security Best Practices

✅ Do's

Store API keys securely

# Use environment variables
export ADMESH_API_KEY="your_api_key"

# Or use a .env file
echo "ADMESH_API_KEY=your_api_key" > .env

Use different keys for different environments

// Different keys for dev/prod
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.ADMESH_PROD_API_KEY
  : process.env.ADMESH_DEV_API_KEY;

Keep API keys on the server

// ✅ Correct - API calls from backend
// pages/api/recommendations.js
export default async function handler(req, res) {
  const response = await fetch('https://api.useadmesh.com/recommend', {
    headers: { 'Authorization': `Bearer ${process.env.ADMESH_API_KEY}` }
  });
  res.json(await response.json());
}

❌ Don'ts

Never commit API keys to version control

# Add to .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

Don't expose keys in client-side code

// ❌ Wrong - API key exposed in browser
const response = await fetch('https://api.useadmesh.com/recommend', {
  headers: { 'Authorization': 'Bearer admesh_prod_abc123xyz789' }
});

// ✅ Correct - API key stays on server
const response = await fetch('/api/recommendations');

Testing Your Integration

Test API Key

# Test with cURL
curl -X POST "https://api.useadmesh.com/recommend" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best CRM software",
    "format": "auto"
  }'

Expected Success Response

{
  "session_id": "sess_1703123456_abc123",
  "intent": {
    "categories": ["crm", "software"],
    "goal": "Find the best CRM solution",
    "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 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"
      }
    ]
  },
  "tokens_used": 500,
  "model_used": "mistralai/mistral-7b-instruct"
}

Next Steps

API Reference - Complete API documentation
Quick Start Guide - Make your first API call
UI SDK Integration - Display recommendations with React components
Get API Keys - Obtain your API credentials

Overview​

Quick Authentication​

HTTP Header (Recommended)​

Query Parameter (Testing Only)​

Direct API Integration​

JavaScript/Node.js​

Python​

Frontend Integration with UI SDK​

Environment Setup​

Development​

Production​

Environment Variables in Code​

API Key Permissions​

Testing Your API Key​

Error Responses​

Invalid API Key​

Missing API Key​

Invalid Request Format​

Server Error​

Error Handling in Code​

JavaScript​

Python​

Security Best Practices​

✅ Do's​

❌ Don'ts​

Testing Your Integration​

Test API Key​

Expected Success Response​

Next Steps​

Overview

Quick Authentication

HTTP Header (Recommended)

Query Parameter (Testing Only)

Direct API Integration

JavaScript/Node.js

Python

Frontend Integration with UI SDK

Environment Setup

Development

Production

Environment Variables in Code

API Key Permissions

Testing Your API Key

Error Responses

Invalid API Key

Missing API Key

Invalid Request Format

Server Error

Error Handling in Code

JavaScript

Python

Security Best Practices

✅ Do's

❌ Don'ts

Testing Your Integration

Test API Key

Expected Success Response

Next Steps