cURL Examples

Ready-to-use cURL commands for testing the Influship API from the command line.

Setup

Environment Variables

Set your API key as an environment variable:

export INFLUSHIP_API_KEY="your_api_key_here"

Or create a .env file and source it:

echo "INFLUSHIP_API_KEY=your_api_key_here" > .env
source .env

Basic Commands

1. Health Check

Test if the API is working:

curl -H "X-API-Key: $INFLUSHIP_API_KEY" \
  https://api.influship.com/health

Expected response:

{
  "ok": true,
  "timestamp": "2025-01-15T10:30:00.000Z",
  "uptime": 12345,
  "memory": {
    "rss": 50000000,
    "heapTotal": 30000000,
    "heapUsed": 20000000
  },
  "version": "0.1.0",
  "environment": "production"
}

2. Test Authentication

Test without API key to see authentication error:

curl https://api.influship.com/health

Expected response:

{
  "error": {
    "code": "unauthorized",
    "message": "API key missing or invalid",
    "request_id": "req_123456789"
  }
}

Search Examples

3. Basic Creator Search

curl -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fitness influencers with high engagement"
  }'

4. Advanced Search with Filters

curl -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fitness influencers with high engagement",
    "filters": {
      "min_followers": 10000,
      "engagement_rate": {
        "min": 0.03
      },
      "platform": ["instagram"],
      "verified": true
    },
    "limit": 10
  }'

5. Search with Pagination

# First page
curl -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fitness influencers",
    "limit": 5
  }'

# Next page (use cursor from previous response)
curl -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fitness influencers",
    "limit": 5,
    "cursor": "eyJvZmZzZXQiOjV9"
  }'

Creator Enrichment Examples

6. Get Multiple Creators by ID (Lite Mode)

curl -X POST https://api.influship.com/v1/creators \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_ids": ["00000000-0000-0000-0000-000000000000"],
    "mode": "lite"
  }'

7. Get Multiple Creators by ID (Detailed Mode)

curl -X POST https://api.influship.com/v1/creators \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_ids": ["00000000-0000-0000-0000-000000000000"],
    "mode": "detailed"
  }'

8. Get Multiple Platform Profiles by Username

curl -X POST https://api.influship.com/v1/profiles \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [
      {
        "platform": "instagram",
        "username": "username"
      }
    ],
    "mode": "detailed"
  }'

Post Analysis Examples

10. Analyze Post by URL

curl -X POST https://api.influship.com/v1/posts/analyze \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "url": "https://instagram.com/p/POST_ID",
    "mode": "detailed"
  }'

11. Analyze Post by ID

curl -X POST https://api.influship.com/v1/posts/analyze \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "id": "POST_ID",
    "mode": "detailed"
  }'

Lookalike Search Examples

12. Find Similar Creators

curl -X POST https://api.influship.com/v1/lookalike \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "limit": 10
  }'

13. Lookalike with Multiple Seeds

curl -X POST https://api.influship.com/v1/lookalike \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "id": "00000000-0000-0000-0000-000000000001"
      }
    ],
    "limit": 20
  }'

Match Scoring Examples

14. Score Creators for Campaign

curl -X POST https://api.influship.com/v1/match \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creators": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "id": "00000000-0000-0000-0000-000000000001"
      }
    ],
    "search_intent": {
      "query": "sustainable fashion campaign",
      "context": "Looking for eco-conscious fashion influencers"
    }
  }'

Job Management Examples

15. List Jobs

curl -H "X-API-Key: $INFLUSHIP_API_KEY" \
  "https://api.influship.com/v1/jobs?limit=10"

16. Get Job Status

curl -H "X-API-Key: $INFLUSHIP_API_KEY" \
  "https://api.influship.com/v1/jobs/job_123456789"

17. Cancel Job

curl -X DELETE \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  "https://api.influship.com/v1/jobs/job_123456789"

Canonical Endpoint Examples

18. Get Multiple Creators with Emails

curl -X POST https://api.influship.com/v1/creators \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_ids": [
      "00000000-0000-0000-0000-000000000000",
      "00000000-0000-0000-0000-000000000001"
    ],
    "mode": "detailed",
    "include": ["emails"]
  }'

19. Get Multiple Platform Profiles

curl -X POST https://api.influship.com/v1/profiles \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [
      {
        "platform": "instagram",
        "username": "fitnessguru"
      },
      {
        "platform": "instagram",
        "username": "wellnesscoach"
      }
    ],
    "mode": "detailed"
  }'

Error Handling Examples

20. Handle Rate Limiting

# Check rate limit headers
curl -I -H "X-API-Key: $INFLUSHIP_API_KEY" \
  https://api.influship.com/v1/search

# Response headers will include:
# RateLimit-Limit: 1000
# RateLimit-Remaining: 999
# RateLimit-Reset: 1640995200

21. Verbose Output for Debugging

curl -v -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "test query"
  }'

22. Save Response to File

curl -X POST https://api.influship.com/v1/creators \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["00000000-0000-0000-0000-000000000000"]}' \
  -o creator_response.json

Testing Scripts

23. Simple Test Script

Create a test script to verify your API key:

#!/bin/bash
# test_api.sh

API_KEY="${INFLUSHIP_API_KEY}"

if [ -z "$API_KEY" ]; then
    echo "Error: INFLUSHIP_API_KEY environment variable not set"
    exit 1
fi

echo "Testing Influship API..."

# Test health endpoint
echo "1. Testing health endpoint..."
health_response=$(curl -s -H "X-API-Key: $API_KEY" https://api.influship.com/health)
echo "Health response: $health_response"

# Test search endpoint
echo "2. Testing search endpoint..."
search_response=$(curl -s -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test query", "limit": 1}')
echo "Search response: $search_response"

echo "API test completed!"

Make it executable and run:

chmod +x test_api.sh
./test_api.sh

24. Batch Testing Script

#!/bin/bash
# batch_test.sh

API_KEY="${INFLUSHIP_API_KEY}"
BASE_URL="https://api.influship.com"

# Test multiple endpoints
endpoints=(
    "GET /health"
    "POST /v1/search"
    "POST /v1/creators"
)

for endpoint in "${endpoints[@]}"; do
    method=$(echo $endpoint | cut -d' ' -f1)
    path=$(echo $endpoint | cut -d' ' -f2)
    
    echo "Testing $method $path..."
    
    if [ "$method" = "GET" ]; then
        curl -s -H "X-API-Key: $API_KEY" "$BASE_URL$path" | jq .
    else
        curl -s -X POST -H "X-API-Key: $API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"query": "test"}' "$BASE_URL$path" | jq .
    fi
    
    echo "---"
done

Tips and Best Practices

Use jq for JSON Formatting

Install jq for better JSON output:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Then use it:
curl -H "X-API-Key: $INFLUSHIP_API_KEY" \
  https://api.influship.com/health | jq .

Handle Rate Limits

# Check rate limit headers and implement backoff
rate_limit_remaining=$(curl -s -I -H "X-API-Key: $API_KEY" \
  https://api.influship.com/v1/search | grep -i "ratelimit-remaining" | cut -d' ' -f2)

if [ "$rate_limit_remaining" -lt 10 ]; then
    echo "Rate limit low, waiting..."
    sleep 60
fi

Use Aliases for Common Commands

Add to your ~/.bashrc or ~/.zshrc:

alias influship-health='curl -H "X-API-Key: $INFLUSHIP_API_KEY" https://api.influship.com/health'
alias influship-search='curl -X POST -H "X-API-Key: $INFLUSHIP_API_KEY" -H "Content-Type: application/json" https://api.influship.com/v1/search'

JavaScript Examples - Node.js and browser examples
Python Examples - Python SDK examples
Authentication Guide - API key setup and security
Error Handling Guide - Comprehensive error handling

Code Examples

​cURL Examples

​Setup

​Environment Variables

​Basic Commands

​1. Health Check

​2. Test Authentication

​Search Examples

​3. Basic Creator Search

​4. Advanced Search with Filters

​5. Search with Pagination

​Creator Enrichment Examples

​6. Get Multiple Creators by ID (Lite Mode)

​7. Get Multiple Creators by ID (Detailed Mode)

​8. Get Multiple Platform Profiles by Username

​Post Analysis Examples

​10. Analyze Post by URL

​11. Analyze Post by ID

​Lookalike Search Examples

​12. Find Similar Creators

​13. Lookalike with Multiple Seeds

​Match Scoring Examples

​14. Score Creators for Campaign

​Job Management Examples

​15. List Jobs

​16. Get Job Status

​17. Cancel Job

​Canonical Endpoint Examples

​18. Get Multiple Creators with Emails

​19. Get Multiple Platform Profiles

​Error Handling Examples

​20. Handle Rate Limiting

​21. Verbose Output for Debugging

​22. Save Response to File

​Testing Scripts

​23. Simple Test Script

​24. Batch Testing Script

​Tips and Best Practices

​Use jq for JSON Formatting

​Handle Rate Limits

​Use Aliases for Common Commands

​Related Examples