Skip to content

Complete API Reference

This page provides a comprehensive overview of all Sherpai Partner API endpoints.

Authentication Endpoints

POST /auth/login

Authenticate with api_client_key and api_secret_key to receive an access token.

Request: 

curl -X POST https://partner-api.sherp.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "api_client_key": "your-client-key",
    "api_secret_key": "your-secret-key"
  }'

Response: 

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user_id": "firebase_user_uid"
}

View detailed documentation →

User Endpoints

GET /me

Get the current authenticated user's profile and accessible brands. Supports cursor-based pagination over the brands array.

Query Parameters: - limit (optional, default 20): Maximum number of brands to return per page (1–100) - cursor (optional): Use the next_cursor value from a previous response to fetch the next page

Request: 

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/me?limit=20"

Response: 

{
  "name": "User Name",
  "brands": [
    {
      "brand_id": 101,
      "brand_name": "Example Brand",
      "fb_accounts": [
        {
          "account_id": 4,
          "account_name": "Loopsider",
          "network_id": "424922021243063"
        }
      ],
      "ig_accounts": [
        {
          "account_id": 2,
          "account_name": "loopsider_official",
          "network_id": null
        }
      ],
      "tk_accounts": [],
      "yt_accounts": [],
      "th_accounts": [],
      "sc_accounts": [],
      "li_accounts": [],
      "da_accounts": [],
      "pi_accounts": []
    }
  ],
  "next_cursor": "eyJpZCI6MTAxLCJjcmVhdGVkX3RpbWUiOm51bGx9"
}

View detailed documentation →

Analytics Endpoint

GET /analytics/

Get unified analytics data with daily breakdown or aggregated totals.

Query Parameters

Parameter Type Required Default Valid Values Description
type string No "daily" "daily", "agg" Analytics output format: "daily" returns daily breakdown with one entry per date, "agg" returns aggregated totals for the entire period
brand_id string No* All accessible brands Single integer or comma-separated integers (e.g., 1 or 1,2,3) Brand identifier(s). *Required if account_id not provided. Multiple brands group results by brand
account_id string No* - Single integer or comma-separated integers (e.g., 4 or 4,2) Account identifier(s). *Required if brand_id not provided. Multiple account_ids require exactly one platform
platform string No All platforms Comma-separated codes: fb (Facebook), ig (Instagram), th (Threads), tk (TikTok), yt (YouTube), sc (Snapchat), li (LinkedIn), da (Dailymotion), pi (Pinterest). Examples: fb, fb,ig,sc Platform filter. If not provided, data is summed across all platforms
since date No Today - 7 days YYYY-MM-DD format (e.g., 2025-01-15) Start date for the analytics period
until date No Today YYYY-MM-DD format (e.g., 2025-01-22) End date for the analytics period
split_by_platform boolean No false true, false When true, results grouped by platform only (aggregates across all brands). When false, results grouped by brand/account

Note: If neither brand_id nor account_id is provided, the API defaults to all accessible brands.

Request Examples:

Daily breakdown with brand_id: 

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&brand_id=1&since=2025-01-15&until=2025-01-22"

Daily breakdown with account_id: 

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=daily&account_id=4,2&since=2025-01-15&until=2025-01-22&platform=fb"

Aggregated totals with account_id: 

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?type=agg&account_id=4&since=2025-01-15&until=2025-01-22&platform=fb"

Response (type=daily): 

{
  "data": [
    {
      "date": "2025-01-22",
      "account_id": 4,
      "account_name": "Loopsider",
      "platform": "fb",
      "revenue": 65.00414789,
      "impressions": 635090,
      "views": 322756,
      "followers_total": 2696849,
      "followers_day": 16,
      "posts_count": 4,
      "interactions": 13597
    }
  ],
  "total": 8,
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"]
}

Response (type=agg): 

{
  "data": [
    {
      "platform": "fb",
      "account_id": 4,
      "name": "Loopsider",
      "network_id": "424922021243063",
      "impressions": 5429041,
      "views": 5429041,
      "views_video": 5192335,
      "revenues": 633,
      "interactions": 73927,
      "interaction_rate": 2.3,
      "link_clicks": 183,
      "posts_per_day": 5.38,
      "new_followers": 1297,
      "followers": 4573975,
      "posts": 43
    }
  ],
  "total": 1,
  "aggregates": {...},
  "since": "2025-01-15",
  "until": "2025-01-22",
  "platforms": ["fb"]
}

Posts Endpoints

GET /posts

Get unified posts from all platforms in a single request.

View detailed documentation →

System Endpoints

GET /health

Health check endpoint for monitoring API status.

Request: 

curl https://partner-api.sherp.ai/health

Response: 

{
  "status": "healthy",
  "service": "sherpai-api"
}

Status: ✅ No authentication required

Error Responses

All endpoints may return these common error responses:

401 Unauthorized

{
  "detail": "Authentication required. Please provide a valid Bearer token in the Authorization header.",
  "error_code": "INVALID_CREDENTIALS",
  "status_code": 401,
  "status": "error"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["query", "brand_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ],
  "error_code": "VALIDATION_ERROR",
  "status_code": 422,
  "status": "error"
}

500 Internal Server Error

{
  "detail": "Internal server error occurred",
  "error_code": "INTERNAL_SERVER_ERROR",
  "status_code": 500,
  "status": "error"
}

Learn more about error handling →

Rate Limits

The API implements rate limiting to ensure fair usage :

  • Standard rate limits apply to all endpoints
  • Rate limit headers are included in responses
  • 429 status code when limits are exceeded

Learn more about rate limits →

Next Steps