Skip to content

api-documentation.md

Latest commit

 

History

History
904 lines (755 loc) · 18.3 KB

api-documentation.md

File metadata and controls

904 lines (755 loc) · 18.3 KB
Raw

ICY API Documentation

Table of Contents

  1. Overview
  2. Authentication
  3. Error Handling
  4. Rate Limiting
  5. API Endpoints
  6. Data Models
  7. Examples
  8. SDKs and Libraries

Overview

The ICY API provides programmatic access to influencer discovery, brand alignment analysis, campaign management, and analytics features. The API follows REST principles and returns JSON responses.

Base URL

https://api.icy-platform.com/api

API Version

Current version: v1

Content Type

All requests should include:

Content-Type: application/json

Authentication

ICY uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header for all authenticated requests.

Obtaining a Token

Sign Up

POST /auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123",
  "confirmPassword": "securepassword123"
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "64f1234567890abcdef12345",
      "email": "user@example.com",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Using the Token

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Session Validation

GET /auth/session
Authorization: Bearer {token}

Error Handling

The API uses standard HTTP status codes and returns consistent error responses.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional error context"
    }
  }
}

Common Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error

Error Codes

  • VALIDATION_ERROR - Request validation failed
  • AUTHENTICATION_REQUIRED - Missing or invalid authentication
  • RESOURCE_NOT_FOUND - Requested resource doesn't exist
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INFLUENCER_NOT_FOUND - Specific influencer not found
  • CAMPAIGN_NOT_FOUND - Specific campaign not found
  • TEMPLATE_NOT_FOUND - Specific template not found

Rate Limiting

API requests are rate-limited to ensure fair usage:

  • Standard endpoints: 100 requests per 15 minutes
  • AI endpoints: 20 requests per hour
  • Search endpoints: 200 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

API Endpoints

Authentication Endpoints

POST /auth/signup

Create a new user account.

Request Body:

{
  "email": "string (required)",
  "password": "string (required, min 8 chars)",
  "confirmPassword": "string (required)"
}

POST /auth/login

Authenticate user and receive token.

Request Body:

{
  "email": "string (required)",
  "password": "string (required)"
}

GET /auth/session

Validate current session token.

Headers: Authorization: Bearer {token}

POST /auth/logout

Invalidate current session token.

Headers: Authorization: Bearer {token}

Brand Management Endpoints

POST /brand/setup

Create or update brand profile.

Headers: Authorization: Bearer {token}

Request Body:

{
  "productDetails": {
    "name": "string (required)",
    "category": "string (required)",
    "description": "string"
  },
  "targetAudience": {
    "demographics": ["string"],
    "interests": ["string"],
    "location": ["string"]
  },
  "brandTone": "professional|casual|friendly",
  "campaignGoals": ["awareness", "sales", "ugc", "partnerships"],
  "platformPreferences": ["instagram", "youtube"],
  "budgetRange": "micro|mid-tier|macro|mixed"
}

GET /brand/profile

Retrieve current brand profile.

Headers: Authorization: Bearer {token}

PUT /brand/profile

Update existing brand profile.

Headers: Authorization: Bearer {token}

Request Body: Same as POST /brand/setup (partial updates allowed)

DELETE /brand/profile

Delete brand profile.

Headers: Authorization: Bearer {token}

Influencer Discovery Endpoints

GET /influencers/search

Search for influencers based on criteria.

Query Parameters:

  • niche (string) - Filter by niche category
  • minFollowers (number) - Minimum follower count
  • maxFollowers (number) - Maximum follower count
  • minEngagement (number) - Minimum engagement rate (0-1)
  • maxEngagement (number) - Maximum engagement rate (0-1)
  • location (string) - Filter by location
  • hasEmail (boolean) - Only influencers with email
  • verified (boolean) - Only verified accounts
  • businessAccount (boolean) - Only business accounts
  • followerTier (string) - micro|mid-tier|macro
  • sortBy (string) - followers|engagement|relevance
  • sortOrder (string) - asc|desc
  • limit (number) - Results per page (max 50)
  • offset (number) - Pagination offset

Response:

{
  "success": true,
  "data": {
    "influencers": [
      {
        "id": "string",
        "username": "string",
        "fullName": "string",
        "followerCount": "number",
        "engagementRate": "number",
        "niche": "string",
        "location": "string",
        "verified": "boolean",
        "businessAccount": "boolean",
        "hasContactInfo": "boolean",
        "followerTier": "string"
      }
    ],
    "total": "number",
    "filters": "object"
  }
}

GET /influencers/stats

Get dataset statistics.

Response:

{
  "success": true,
  "data": {
    "totalInfluencers": "number",
    "withEmail": "number",
    "verified": "number",
    "businessAccounts": "number",
    "followerTiers": {
      "micro": "number",
      "mid-tier": "number",
      "macro": "number"
    },
    "niches": {
      "category": "count"
    },
    "countries": {
      "country": "count"
    }
  }
}

GET /influencers/:id

Get specific influencer details.

Parameters:

  • id (string) - Influencer ID

Response:

{
  "success": true,
  "data": {
    "id": "string",
    "username": "string",
    "fullName": "string",
    "bio": "string",
    "followerCount": "number",
    "followingCount": "number",
    "postCount": "number",
    "engagementRate": "number",
    "avgLikes": "number",
    "avgComments": "number",
    "niche": "string",
    "location": "string",
    "verified": "boolean",
    "businessAccount": "boolean",
    "contactInfo": {
      "email": "string",
      "website": "string"
    }
  }
}

POST /influencers/analyze

Analyze influencer for brand alignment.

Request Body:

{
  "influencerId": "string (required)",
  "brandCriteria": {
    "niche": "string",
    "targetAudience": ["string"],
    "keywords": ["string"]
  }
}

POST /influencers/validate

Validate influencer data structure.

Request Body:

{
  "id": "string",
  "username": "string",
  "followerCount": "number",
  "engagementRate": "number"
}

Campaign Management Endpoints

POST /campaigns

Create a new campaign.

Headers: Authorization: Bearer {token}

Request Body:

{
  "name": "string (required)",
  "description": "string",
  "targetInfluencers": ["string"],
  "messageTemplateId": "string",
  "campaignGoals": ["string"],
  "budget": "number",
  "startDate": "ISO date string",
  "endDate": "ISO date string"
}

GET /campaigns

List user's campaigns.

Headers: Authorization: Bearer {token}

Query Parameters:

  • status (string) - Filter by status
  • limit (number) - Results per page
  • offset (number) - Pagination offset

GET /campaigns/:id

Get specific campaign details.

Headers: Authorization: Bearer {token}

Parameters:

  • id (string) - Campaign ID

PUT /campaigns/:id

Update campaign.

Headers: Authorization: Bearer {token}

Parameters:

  • id (string) - Campaign ID

Request Body: Partial campaign object

POST /campaigns/:id/send

Send campaign messages.

Headers: Authorization: Bearer {token}

Parameters:

  • id (string) - Campaign ID

Request Body:

{
  "customMessage": "string (optional)",
  "sendImmediately": "boolean"
}

DELETE /campaigns/:id

Delete campaign.

Headers: Authorization: Bearer {token}

Parameters:

  • id (string) - Campaign ID

Message Template Endpoints

POST /templates

Create message template.

Headers: Authorization: Bearer {token}

Request Body:

{
  "name": "string (required)",
  "subject": "string (required)",
  "content": "string (required)",
  "type": "collaboration|partnership|event|follow_up",
  "brandTone": "professional|casual|friendly"
}

GET /templates

List user's templates.

Headers: Authorization: Bearer {token}

GET /templates/:id

Get specific template.

Headers: Authorization: Bearer {token}

PUT /templates/:id

Update template.

Headers: Authorization: Bearer {token}

POST /templates/:id/personalize

Personalize template for specific influencer.

Headers: Authorization: Bearer {token}

Request Body:

{
  "influencerId": "string (required)",
  "customData": {
    "brandName": "string",
    "senderName": "string",
    "recentPostTopic": "string"
  }
}

DELETE /templates/:id

Delete template.

Headers: Authorization: Bearer {token}

Analytics Endpoints

GET /analytics/dashboard

Get dashboard analytics.

Headers: Authorization: Bearer {token}

Response:

{
  "success": true,
  "data": {
    "totalCampaigns": "number",
    "activeCampaigns": "number",
    "totalInfluencersContacted": "number",
    "overallMetrics": {
      "messagesSent": "number",
      "deliveryRate": "number",
      "responseRate": "number",
      "engagementRate": "number"
    },
    "recentActivity": ["object"]
  }
}

GET /analytics/campaigns/:id

Get campaign-specific analytics.

Headers: Authorization: Bearer {token}

GET /analytics/export/:id

Export campaign data as CSV.

Headers: Authorization: Bearer {token}

GET /analytics/trends

Get performance trends.

Headers: Authorization: Bearer {token}

Query Parameters:

  • period (string) - 7days|30days|90days|1year

AI Feature Endpoints

POST /ai/analyze-authenticity

Analyze influencer content authenticity.

Request Body:

{
  "influencerId": "string (required)",
  "analysisType": "content_authenticity"
}

POST /ai/brand-alignment

Analyze brand alignment using AI.

Request Body:

{
  "influencerId": "string (required)",
  "brandCriteria": {
    "niche": "string",
    "targetAudience": ["string"],
    "keywords": ["string"]
  }
}

POST /ai/generate-message

Generate AI-powered outreach message.

Request Body:

{
  "influencerId": "string (required)",
  "brandInfo": {
    "name": "string (required)",
    "description": "string",
    "tone": "professional|casual|friendly"
  },
  "messageType": "initial_outreach|follow_up|partnership",
  "campaignType": "string"
}

POST /ai/smart-match

Get AI-powered influencer recommendations.

Request Body:

{
  "brandCriteria": {
    "niche": "string",
    "targetAudience": ["string"],
    "keywords": ["string"]
  },
  "campaignType": "string",
  "budget": "string",
  "maxResults": "number"
}

Data Models

User Model

{
  "_id": "ObjectId",
  "email": "string",
  "password": "string (hashed)",
  "createdAt": "Date",
  "lastLogin": "Date"
}

Brand Profile Model

{
  "_id": "ObjectId",
  "userId": "ObjectId",
  "productDetails": {
    "name": "string",
    "category": "string",
    "description": "string"
  },
  "targetAudience": {
    "demographics": ["string"],
    "interests": ["string"],
    "location": ["string"]
  },
  "brandTone": "string",
  "campaignGoals": ["string"],
  "platformPreferences": ["string"],
  "budgetRange": "string",
  "createdAt": "Date",
  "updatedAt": "Date"
}

Influencer Model

{
  "id": "string",
  "username": "string",
  "fullName": "string",
  "bio": "string",
  "followerCount": "number",
  "followingCount": "number",
  "postCount": "number",
  "engagementRate": "number",
  "avgLikes": "number",
  "avgComments": "number",
  "niche": "string",
  "location": "string",
  "verified": "boolean",
  "businessAccount": "boolean",
  "contactInfo": {
    "email": "string",
    "website": "string"
  },
  "followerTier": "string",
  "hasContactInfo": "boolean"
}

Campaign Model

{
  "_id": "ObjectId",
  "userId": "ObjectId",
  "brandId": "ObjectId",
  "name": "string",
  "description": "string",
  "targetInfluencers": ["string"],
  "messageTemplateId": "ObjectId",
  "personalizedMessages": [{
    "influencerId": "string",
    "message": "string",
    "status": "string",
    "sentAt": "Date",
    "deliveredAt": "Date"
  }],
  "campaignGoals": ["string"],
  "budget": "number",
  "status": "string",
  "startDate": "Date",
  "endDate": "Date",
  "createdAt": "Date",
  "updatedAt": "Date"
}

Message Template Model

{
  "_id": "ObjectId",
  "userId": "ObjectId",
  "name": "string",
  "subject": "string",
  "content": "string",
  "type": "string",
  "brandTone": "string",
  "placeholders": ["string"],
  "createdAt": "Date",
  "updatedAt": "Date"
}

Examples

Complete Workflow Example

1. Authenticate

// Sign up
const signupResponse = await fetch('/api/auth/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'brand@example.com',
    password: 'securepass123',
    confirmPassword: 'securepass123'
  })
});

const { token } = (await signupResponse.json()).data;

2. Setup Brand Profile

const brandResponse = await fetch('/api/brand/setup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    productDetails: {
      name: 'EcoFashion Brand',
      category: 'Fashion',
      description: 'Sustainable fashion for conscious consumers'
    },
    targetAudience: {
      demographics: ['25-35', 'Female'],
      interests: ['Fashion', 'Sustainability', 'Lifestyle'],
      location: ['United States', 'Canada']
    },
    brandTone: 'professional',
    campaignGoals: ['awareness', 'sales'],
    platformPreferences: ['instagram'],
    budgetRange: 'mid-tier'
  })
});

3. Search for Influencers

const searchResponse = await fetch(
  '/api/influencers/search?niche=fashion&minFollowers=50000&maxFollowers=500000&hasEmail=true&limit=10'
);

const { influencers } = (await searchResponse.json()).data;

4. Analyze Brand Alignment

const analysisResponse = await fetch('/api/influencers/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    influencerId: influencers[0].id,
    brandCriteria: {
      niche: 'fashion',
      targetAudience: ['25-35', 'Female'],
      keywords: ['sustainable', 'fashion', 'eco-friendly']
    }
  })
});

5. Generate AI Message

const messageResponse = await fetch('/api/ai/generate-message', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    influencerId: influencers[0].id,
    brandInfo: {
      name: 'EcoFashion Brand',
      description: 'Sustainable fashion for conscious consumers',
      tone: 'professional'
    },
    messageType: 'initial_outreach'
  })
});

6. Create Campaign

const campaignResponse = await fetch('/api/campaigns', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    name: 'Spring Sustainability Campaign',
    description: 'Promoting our new eco-friendly spring collection',
    targetInfluencers: [influencers[0].id],
    campaignGoals: ['awareness', 'sales'],
    budget: 5000
  })
});

const { campaign } = (await campaignResponse.json()).data;

7. Send Campaign

const sendResponse = await fetch(`/api/campaigns/${campaign._id}/send`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    sendImmediately: true
  })
});

8. Monitor Analytics

const analyticsResponse = await fetch(`/api/analytics/campaigns/${campaign._id}`, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const metrics = (await analyticsResponse.json()).data.metrics;
console.log('Campaign Performance:', metrics);

SDKs and Libraries

JavaScript/Node.js SDK

npm install icy-api-sdk
const ICY = require('icy-api-sdk');

const client = new ICY({
  apiKey: 'your-api-key',
  baseURL: 'https://api.icy-platform.com/api'
});

// Search influencers
const influencers = await client.influencers.search({
  niche: 'fashion',
  minFollowers: 10000
});

// Create campaign
const campaign = await client.campaigns.create({
  name: 'My Campaign',
  targetInfluencers: ['influencer-id']
});

Python SDK

pip install icy-python-sdk
from icy_sdk import ICYClient

client = ICYClient(api_key='your-api-key')

# Search influencers
influencers = client.influencers.search(
    niche='fashion',
    min_followers=10000
)

# Analyze brand alignment
analysis = client.influencers.analyze(
    influencer_id='influencer-id',
    brand_criteria={
        'niche': 'fashion',
        'keywords': ['sustainable', 'eco-friendly']
    }
)

cURL Examples

Search Influencers

curl -X GET "https://api.icy-platform.com/api/influencers/search?niche=fashion&limit=5" \
  -H "Content-Type: application/json"

Create Campaign

curl -X POST "https://api.icy-platform.com/api/campaigns" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Test Campaign",
    "targetInfluencers": ["influencer-id"],
    "campaignGoals": ["awareness"]
  }'

For more examples and detailed integration guides, visit our Developer Portal.