# Celavii Documentation - LLM-Friendly Index
# Last updated: 2026-02-17
# This file provides a machine-readable reference for Celavii
# Includes: API schemas, concept summaries, and code examples

## About Celavii
Celavii is a Creator Intelligence Platform that helps brands discover creators, manage relationships, track campaigns, and measure ROI. Key capabilities:
- AI-powered creator discovery with niche, location, and engagement filters
- Profile enhancement with brand affinities and demographic analysis
- Campaign tracking with ROI measurement
- CRM pipeline for relationship management
- Live Capture for finding influencers in your customer base

## API Base URL
https://api.celavii.com/v1

## Authentication
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEY

API keys are created in Settings > Security. Each key has scopes (read, write, admin).

---

# CORE CONCEPTS

## Credits
Credits are the currency for data operations. They reset monthly based on billing cycle.
- Credits do NOT roll over to the next month
- Usage tracked in real-time at /usage endpoint
- Overage protection available (Settings > Billing)

Credit costs:
- Profile search: 1 credit
- Profile enhancement (basic): 1 credit per profile
- Profile enhancement (enhanced): 2 credits per profile
- Immediate refinement: 1 credit per profile
- Follower/following data: 2 credits
- Location data: 1 credit
- Hashtag data: 1 credit
- Cohort analysis: 2 credits
- AI Studio (images/video/audio): varies by model and duration

## Affinities
AI-detected brand and topic associations extracted from creator content.
Types: brand, topic, location, category
Confidence scores: 0.0 to 1.0 (higher = stronger affinity)
Example: A fitness creator might have affinities for "Nike" (brand, 0.85), "fitness" (topic, 0.92)

## Hot Scores
Engagement velocity metric measuring recent performance vs. historical average.
Range: 0-100 (higher = trending upward)
Calculation: Weighted average of engagement rate, post frequency, follower growth over 30 days
Use case: Find creators with growing momentum for time-sensitive campaigns

## Data Refinement
AI enhancement process that enriches creator profiles with:
- Niche classification (primary, secondary)
- Demographic analysis (age, gender, location)
- Brand affinities (topics, brands, interests)
- Content themes and posting patterns
- Contact information extraction

Two modes:
- Basic (1 credit): Niche, demographics, basic affinities
- Enhanced (2 credits): All basic + deep content analysis, detailed affinities

## Workspaces
Organizational containers for teams, campaigns, and data.
Use cases: Separate by client, campaign, region, or team
Permissions: Owner, Admin, Member, Viewer

---

# API REFERENCE

## Profiles API

### Search Profiles
GET /profiles/search
Query params: query, niche, location, min_followers, max_followers, gender, has_contact, limit, cursor

Example request:
```
curl -X GET "https://api.celavii.com/v1/profiles/search?niche=fitness&min_followers=10000&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response:
```json
{
  "data": [
    {
      "id": "12345",
      "username": "fitness_creator",
      "display_name": "Fitness Creator",
      "followers": 125000,
      "engagement_rate": 4.5,
      "niche": "fitness",
      "location": "Los Angeles, CA",
      "hot_score": 78
    }
  ],
  "pagination": { "cursor": "abc123", "has_more": true }
}
```

### Get Profile Details
GET /profiles/:id

Response includes: username, display_name, bio, followers, following, posts_count, engagement_rate, niche, location, contact_info, affinities, hot_score, enhanced_at

### Enhance Profile
POST /profiles/enhance
Body: { "identifiers": ["username1", "username2"], "mode": "basic" | "enhanced" }
Returns: job_id (poll GET /jobs/:job_id for status)

## Lists API

### Create List
POST /lists
Body: { "name": "Campaign Q1", "description": "Q1 influencer campaign" }

### Add Members
POST /lists/:id/members
Body: { "identifiers": ["username1", "username2"] }

## Campaigns API

### Get Campaign Metrics
GET /campaigns/:id/metrics

Response:
```json
{
  "total_creators": 25,
  "total_posts": 142,
  "total_reach": 2500000,
  "total_engagement": 125000,
  "avg_engagement_rate": 5.2,
  "estimated_value": 45000
}
```

## Analytics API

### Cohort Analysis
POST /cohort/analyze
Body: { "identifiers": ["user1", "user2"], "include": ["affinities", "demographics", "engagement_stats"] }

Response includes aggregate stats, demographic breakdowns, shared affinities, and engagement patterns.

## Documentation Pages

### Getting Started
- /docs - Documentation home & introduction
- /docs/quickstart - Getting started in 5 minutes

### Guides
- /docs/guides/discovery - Creator discovery guide
- /docs/guides/ai-studio - AI content generation
- /docs/guides/analyze - Campaign tracking & analytics
- /docs/guides/manage - CRM & relationship management
- /docs/guides/network - Network exploration
- /docs/guides/email - Email outreach campaigns
- /docs/guides/actions - Task management system
- /docs/guides/payments - Creator payment management
- /docs/guides/live-capture - Find influencers in your network

### Concepts
- /docs/concepts/credits - Credit system & pricing
- /docs/concepts/affinities - AI-detected brand affinities
- /docs/concepts/hot-scores - Creator engagement scoring
- /docs/concepts/data-refinement - AI profile enhancement
- /docs/concepts/workspaces - Team organization

### API Reference
- /docs/api/authentication - API key management
- /docs/api/endpoints - Complete API reference
- /docs/api/rate-limits - Rate limiting & best practices

### Settings
- /docs/settings/billing - Subscription & payments
- /docs/settings/teams - Team member management
- /docs/settings/profile - Personal profile settings
- /docs/settings/security - 2FA & security options
- /docs/settings/organization - Organization settings
- /docs/settings/notifications - Notification preferences
- /docs/settings/integrations - Third-party connections
- /docs/settings/data - Data export & management

### Other
- /docs/changelog - Product updates & releases

## Rate Limits
- Free: 100 requests/minute
- Pro: 500 requests/minute
- Business: 1000 requests/minute
- Enterprise: Custom

## Credit Costs
- Profile search: 1 credit
- Profile enhancement (basic): 1 credit
- Profile enhancement (enhanced): 2 credits
- Immediate refinement: 1 credit
- Bulk enhancement: 1-2 credits per profile
- Follower/following data: 2 credits
- Location data: 1 credit
- Hashtag data: 1 credit
- Cohort analysis: 2 credits
- AI Studio (images): varies by model
- AI Studio (video): varies by duration
- AI Studio (audio): varies by length

## Support
- Email: support@celavii.com
- Documentation: https://celavii.com/docs
- Status: https://status.celavii.com