Getting Started

Welcome to the Sherpai Partner API! This guide will walk you through everything you need to go from zero to making your first API call in just a few minutes.

---

What is the Sherpai Partner API?

The Sherpai Partner API is a comprehensive RESTful API that provides access to social media analytics data, user profiles, and dashboard metrics across 9 major social media platforms (Facebook, Instagram, TikTok, YouTube, LinkedIn, Threads, Snapchat, Dailymotion, and Pinterest). It enables partners to integrate social media analytics into their own applications and services.

---

Prerequisites

Before you begin, make sure you have:

• ✅ Sherpai Partner Account: Contact your partner representative to get access
• ✅ API Credentials: API client key and secret key (provided by your partner representative)
• ✅ Basic REST API Knowledge: Understanding of HTTP methods (GET, POST), status codes, and JSON
• ✅ HTTP Client: curl, Postman, or a programming language with HTTP library

API Technical Specifications

Specification	Details
Base URL	https://partner-api.sherp.ai
Protocol	HTTPS (TLS 1.2+)
HTTP Methods	GET, POST
Content Type	application/json
Response Format	JSON
Authentication	JWT Bearer Token
Rate Limits	10,000 requests/minute
Token Expiry	1 hour (3600 seconds)

---

Step 1: Get Your API Credentials

To access the API, you'll need API client credentials from your Sherpai partner representative:

1. Contact your partner representative to obtain:
2. API Client Key: Identifier for your account
3. API Secret Key: Secret for authentication
4. Store credentials securely:
5. ✅ Never commit credentials to version control
6. ✅ Use environment variables or secure secret management
7. ✅ Store in secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)

Learn more about authentication →

---

Step 2: Authenticate and Get Your Access Token

Use the /auth/login endpoint to exchange your API credentials for a JWT access token.

Code Examples

cURLPythonJavaScript (Node.js)

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"
  }'

import requests

response = requests.post(
    'https://partner-api.sherp.ai/auth/login',
    json={
        'api_client_key': 'your-client-key',
        'api_secret_key': 'your-secret-key'
    }
)

data = response.json()
access_token = data['access_token']
print(f"Token expires in: {data['expires_in']} seconds")

const response = await fetch('https://partner-api.sherp.ai/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_client_key: 'your-client-key',
    api_secret_key: 'your-secret-key'
  })
});

const data = await response.json();
const accessToken = data.access_token;
console.log(`Token expires in: ${data.expires_in} seconds`);

Success Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user_id": "user_uid"
}

Token Management

• Save the access_token - you'll need it for all subsequent API requests
• Token expiry: Tokens expire after 1 hour (3600 seconds)
• Automatic refresh: Implement token refresh logic in your application
• Security: Never expose tokens in URLs, logs, or client-side code

Complete authentication guide →

---

Step 3: Make Your First API Call

Now that you have an access token, let's make your first API call to get your user profile:

cURLPythonJavaScript (Node.js)

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://partner-api.sherp.ai/me

import requests

headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get('https://partner-api.sherp.ai/me', headers=headers)
user = response.json()
print(f"User: {user['name']}")

const response = await fetch('https://partner-api.sherp.ai/me', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

const user = await response.json();
console.log(`User: ${user.name}`);

Expected Response:

{
  "name": "Your Name",
  "brands": [
    {
      "brand_id": 101,
      "brand_name": "Example Brand",
      "fb_accounts": [
        {
          "account_id": 4,
          "account_name": "Example Brand",
          "network_id": "123456789"
        },
        {
          "account_id": 15,
          "account_name": "Example Brand - Main Page",
          "network_id": "987654321"
        }
      ],
      "ig_accounts": [
        {
          "account_id": 101,
          "account_name": "examplebrand_official",
          "network_id": "123456789"
        },
        {
          "account_id": 202,
          "account_name": "examplebrand_news",
          "network_id": null
        }
      ]
    },
    {
      "brand_id": 202,
      "brand_name": "Another Brand",
      "fb_accounts": [],
      "ig_accounts": [
        {
          "account_id": 303,
          "account_name": "anotherbrand",
          "network_id": "456789123"
        }
      ]
    }
  ],
  "next_cursor": null
}

🎉 Congratulations! You've successfully made your first API call.

Follow the complete quickstart guide →

---

Step 4: Explore the API

The Sherpai Partner API provides comprehensive endpoints across multiple categories:

Core Endpoints

Category	Endpoints	Description
Authentication	POST /auth/login	Get access token
Users	GET /me	User brands and account
Posts	GET /posts	Unified posts from all platforms
Analytics	GET /analytics/	Account or brand analytics

System Endpoints

Endpoint	Description
GET /health	Health check (no authentication required)

View complete API reference →

---

Quick Reference

Rate Limits & Quotas

Limit Type	Value	Period
Application Limit	10,000 requests	Per minute
Token Lifetime	1 hour	3,600 seconds

Rate Limit Headers

All responses include rate limit information: - X-RateLimit-Limit: Maximum requests allowed - X-RateLimit-Remaining: Requests remaining - X-RateLimit-Reset: Unix timestamp when limit resets

Example: Viewing Rate Limit Headers

All API responses include rate limit headers. Here's how to access them in different languages:

cURLPythonJavaScript (Node.js)

Use the -i flag to see response headers:

curl -i -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://partner-api.sherp.ai/analytics/?brand_id=1234,5678&limit=10"

Example Response:

HTTP/1.1 200 OK
content-type: application/json
x-ratelimit-limit: 1000
x-ratelimit-remaining: 999
x-ratelimit-reset: 1763652471
content-length: 1234

{
  "data": [
    {
      "account_id": 4,
      "account_name": "Example Account",
      "metrics": {
        "followers": 12500,
        "engagement_rate": 3.2
      }
    }
  ],
  "next_cursor": null
}

Access headers from the response object:

import requests

headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(
    'https://partner-api.sherp.ai/analytics/',
    params={'brand_id': '1234,5678', 'limit': 10},
    headers=headers
)

# Access rate limit headers
rate_limit_limit = response.headers.get('X-RateLimit-Limit')
rate_limit_remaining = response.headers.get('X-RateLimit-Remaining')
rate_limit_reset = response.headers.get('X-RateLimit-Reset')

print(f"Limit: {rate_limit_limit}")
print(f"Remaining: {rate_limit_remaining}")
print(f"Reset at: {rate_limit_reset}")

data = response.json()
print(f"Data: {data}")

Access headers from the response object:

const response = await fetch(
  'https://partner-api.sherp.ai/analytics/?brand_id=1234,5678&limit=10',
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

// Access rate limit headers
const rateLimitLimit = response.headers.get('X-RateLimit-Limit');
const rateLimitRemaining = response.headers.get('X-RateLimit-Remaining');
const rateLimitReset = response.headers.get('X-RateLimit-Reset');

console.log(`Limit: ${rateLimitLimit}`);
console.log(`Remaining: ${rateLimitRemaining}`);
console.log(`Reset at: ${rateLimitReset}`);

const data = await response.json();
console.log('Data:', data);

Learn more about rate limiting →

Common Error Codes

Status Code	Error Code	Description	Solution
400	BAD_REQUEST	Invalid request	Check request parameters
401	INVALID_CREDENTIALS	Missing or invalid token	Re-authenticate
401	TOKEN_EXPIRED	Token has expired	Get new token
403	INSUFFICIENT_PERMISSIONS	Insufficient permissions	Check user roles
404	BRAND_NOT_FOUND	Resource not found	Verify resource ID
422	VALIDATION_ERROR	Invalid request parameters	Check parameter format
429	RATE_LIMIT_EXCEEDED	Rate limit exceeded	Wait and retry with backoff
500	INTERNAL_SERVER_ERROR	Server error	Retry after delay

Complete error handling guide →

---

---

Need Help?

Contact us at tech@loopsider.com

Documentation Resources

• FAQ - Common questions and solutions
• Error Handling - Troubleshoot API errors
• Rate Limiting - Understand usage limits

---

Next Steps

• Authentication

  ---

  Set up authentication and get your access tokens.

  Authentication Guide

• Quickstart

  ---

  Make your first API call and see results immediately.

  Quickstart Guide

• API Reference

  ---

  Browse complete endpoint documentation with examples.

  API Reference