Crowdswell API Documentation

Overview

The Crowdswell API is a REST API that provides robust functionality for building modern influencer marketing platforms. It handles everything from campaign management to analytics and reporting.

🎯 Campaign Management

Create and manage influencer marketing campaigns with detailed requirements and deliverables.

👥 Creator Applications

Handle creator applications to campaigns with proposal management and approval workflows.

📊 Analytics & Reporting

Real-time analytics, performance tracking, and comprehensive reporting capabilities.

🔍 Advanced Search

Powerful search with full-text search, filtering, faceting, and autocomplete suggestions.

📁 File Management

Upload, process, and manage files with automatic thumbnail generation and metadata extraction.

⚡ High Performance

Redis caching, bulk operations, and optimized endpoints for maximum performance.

🚀 Quick Start

Get up and running with the Crowdswell API in minutes:

curl "https://ostendov3.nucleotto.com/api/campaigns?status=active&limit=10" \
  -H "Content-Type: application/json"

Authentication

Currently, the API endpoints are open for development purposes. Authentication will be implemented in future versions using API keys and OAuth 2.0.

Response Format

All API responses follow a consistent structure:

{
  "success": true,
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

HTTP Status Codes

200

Success - Request completed successfully

201

Created - Resource created successfully

400

Bad Request - Invalid parameters

404

Not Found - Resource doesn't exist

429

Rate Limited - Too many requests

500

Server Error - Internal server error

Campaigns

Campaigns represent job postings created by brands for creators to apply to. Each campaign defines specific requirements, compensation, and deliverables.

GET /api/campaigns

List all campaigns with optional filtering and pagination.

Parameters

Name	Type	Description
`status`	string	Filter by status (draft, active, paused, completed)
`category`	string	Filter by campaign category
`brandId`	string	Filter by brand ID
`budget_min`	number	Minimum budget filter
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 10, max: 100)

Example Request

curl "https://ostendov3.nucleotto.com/api/campaigns?status=active&category=fashion" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "_id": "6150d3c8e8b9a234567890ef",
        "title": "Summer Fashion Campaign 2024",
        "description": "Seeking fashion influencers for our summer collection launch",
        "category": "fashion",
        "budget": 5000,
        "brandId": "6150d3c8e8b9a234567890cd",
        "status": "active",
        "requirements": {
          "minFollowers": 10000,
          "platforms": ["instagram", "tiktok"]
        },
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 28,
    "totalPages": 3
  }
}

POST /api/campaigns

Create a new campaign.

Request Body

{
  "title": "Summer Fashion Campaign 2024",
  "description": "Seeking fashion influencers for summer collection launch",
  "category": "fashion",
  "budget": 5000,
  "brandId": "6150d3c8e8b9a234567890cd",
  "requirements": {
    "minFollowers": 10000,
    "platforms": ["instagram", "tiktok"],
    "demographics": ["18-35", "female"]
  },
  "deliverables": [
    {
      "type": "instagram_post",
      "quantity": 2,
      "description": "Feed posts showcasing summer outfits"
    }
  ],
  "applicationDeadline": "2024-07-01T23:59:59.000Z",
  "campaignStartDate": "2024-07-15T00:00:00.000Z",
  "campaignEndDate": "2024-08-15T00:00:00.000Z"
}

Quick Start

Get up and running with the Crowdswell API in just a few steps.

1. Make Your First Request

curl "https://ostendov3.nucleotto.com/api/campaigns?status=active&limit=5" \
  -H "Content-Type: application/json"

2. Create a Campaign

curl -X POST "https://ostendov3.nucleotto.com/api/campaigns" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Campaign",
    "description": "A test campaign",
    "budget": 1000,
    "brandId": "your_brand_id_here"
  }'

3. Search for Creators

curl -X POST "https://ostendov3.nucleotto.com/api/search/creators" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fashion",
    "filters": {"status": "active"},
    "limit": 10
  }'

Users

Manage user accounts including creators, brands, and administrators.

GET /api/users

List all users with pagination and search capabilities.

Query Parameters

page (optional): Page number for pagination (default: 1)
limit (optional): Number of users per page (default: 10)
search (optional): Search by name or email

Example Request

GET /api/users?search=jane&page=1&limit=20

GET /api/users/{id}

Retrieve a specific user by ID.

GET /api/users/507f1f77bcf86cd799439011

POST /api/users

Create a new user account with profile information.

{ "name": "Jane Smith", "email": "[email protected]", "userType": "creator", "bio": "Fashion and lifestyle content creator", "location": "Los Angeles, CA", "socialLinks": { "instagram": "@janesmith", "tiktok": "@janesmith_content" } }

PUT /api/users/{id}

Update user profile information and settings.

{
  "name": "Jane Smith-Johnson",
  "bio": "Updated bio with new focus on sustainable fashion",
  "location": "San Francisco, CA",
  "status": "active"
}

DELETE /api/users/{id}

Delete a user account (soft delete to preserve data integrity).

DELETE /api/users/507f1f77bcf86cd799439011

Applications

Handle creator applications to campaigns with proposal management.

POST /api/applications

Submit an application to a campaign.

{
  "campaignId": "campaign_id_here",
  "creatorId": "creator_id_here",
  "proposal": {
    "message": "I'd love to work on this campaign...",
    "proposedRate": 1500
  }
}

Brands

Manage brand profiles and company information.

POST /api/brands

Create a new brand profile.

{
  "name": "Fashion Forward Co.",
  "description": "Premium fashion brand",
  "industry": "fashion",
  "website": "https://fashionforward.com"
}

Creators

Manage creator profiles, portfolios, and performance metrics.

POST /api/creators/{id}/review

Add a review for a creator after campaign completion.

{
  "rating": 5,
  "comment": "Excellent work, great content quality",
  "campaignId": "campaign_id_here"
}

Events

Manage events, webinars, and creator registrations.

POST /api/events/{id}/register

Register a creator for an event.

{
  "creatorId": "creator_id_here",
  "eventId": "event_id_here"
}

Placements

Track content deliverables and performance metrics.

PUT /api/placements/{id}/submit-content

Submit content for a placement.

{
  "contentUrl": "https://instagram.com/p/ABC123",
  "contentType": "instagram_post",
  "metadata": {
    "caption": "Amazing product! #ad",
    "hashtags": ["#ad", "#sponsored"]
  }
}

Tasks

Project management and task tracking for campaigns, placements, and general project management.

GET /api/tasks

Retrieve all tasks with optional filtering and pagination.

Query Parameters

page (optional): Page number for pagination (default: 1)
limit (optional): Number of tasks per page (default: 10)
assignedTo (optional): Filter by assigned user ID
createdBy (optional): Filter by creator user ID
status (optional): Filter by status (pending, in_progress, completed, cancelled)
priority (optional): Filter by priority (low, medium, high, urgent)
dueDate (optional): Filter by due date (YYYY-MM-DD format)

GET /api/tasks?status=in_progress&priority=high&page=1&limit=20

GET /api/tasks/{id}

Retrieve a specific task by ID.

GET /api/tasks/507f1f77bcf86cd799439011

POST /api/tasks

Create a new task with assignment and deadline capabilities.

Required Fields

title: Task title
createdBy: User ID of task creator

{
  "title": "Create campaign mockups",
  "description": "Design initial mockups for summer fashion campaign",
  "assignedTo": "507f1f77bcf86cd799439012",
  "createdBy": "507f1f77bcf86cd799439013",
  "dueDate": "2024-02-15T09:00:00Z",
  "priority": "high",
  "tags": ["design", "mockup", "campaign"],
  "relatedCampaignId": "507f1f77bcf86cd799439014",
  "relatedPlacementId": "507f1f77bcf86cd799439015"
}

PUT /api/tasks/{id}/status

Update task status with automatic progress tracking.

Valid Status Values

pending: Task not yet started
in_progress: Task currently being worked on
completed: Task finished (auto-sets progress to 100%)
cancelled: Task cancelled

{
  "status": "in_progress"
}

PUT /api/tasks/{id}/progress

Update task progress percentage (0-100) with automatic status updates.

{
  "progress": 75
}

POST /api/tasks/{id}/comment

Add a comment to a task for collaboration and progress tracking.

{
  "userId": "507f1f77bcf86cd799439012",
  "comment": "Initial mockups completed, moving to review phase"
}

PUT /api/tasks/{id}

Update task details (excluding system fields like createdBy, createdAt, comments).

{
  "title": "Updated task title",
  "description": "Updated description",
  "priority": "urgent",
  "dueDate": "2024-02-20T09:00:00Z"
}

DELETE /api/tasks/{id}

Permanently delete a task.

DELETE /api/tasks/507f1f77bcf86cd799439011

Jobs

Manage job postings, applications, and hiring workflows for creator positions.

GET /api/jobs

Retrieve all job postings with filtering and pagination.

Query Parameters

page (optional): Page number for pagination (default: 1)
limit (optional): Number of jobs per page (default: 10)
jobType (optional): Filter by job type (full-time, part-time, contract, freelance, campaign, internship)
status (optional): Filter by status (active, closed, draft)
brandId (optional): Filter by brand ID
category (optional): Filter by job category
location (optional): Filter by location (case-insensitive partial match)

GET /api/jobs?jobType=freelance&status=active&category=content&location=remote

GET /api/jobs/{id}

Retrieve a specific job posting by ID.

GET /api/jobs/507f1f77bcf86cd799439011

POST /api/jobs

Create a new job posting with compensation and requirement details.

Required Fields

title: Job title
description: Job description
jobType: Type of job (full-time, part-time, contract, freelance, campaign, internship)

{
  "title": "Fashion Content Creator",
  "description": "Looking for a creative individual to produce fashion content for our summer campaign",
  "jobType": "freelance",
  "brandId": "507f1f77bcf86cd799439012",
  "category": "content creation",
  "location": "Los Angeles, CA",
  "requirements": [
    "2+ years experience in fashion content",
    "Portfolio of previous work",
    "Own camera equipment"
  ],
  "compensation": {
    "type": "project",
    "amount": 2500,
    "currency": "USD"
  },
  "deadline": "2024-03-01T23:59:59Z",
  "tags": ["fashion", "content", "summer"]
}

POST /api/jobs/{id}/apply

Submit an application for a job posting.

Required Fields

applicantId: ID of the user applying

{
  "applicantId": "507f1f77bcf86cd799439013",
  "coverLetter": "I'm excited about this opportunity to create fashion content for your brand. My experience in lifestyle photography and fashion styling makes me a perfect fit...",
  "portfolioLinks": [
    "https://myportfolio.com/fashion-work",
    "https://instagram.com/my_fashion_content"
  ],
  "resumeUrl": "https://drive.google.com/file/d/resume.pdf"
}

GET /api/jobs/{id}/applications

Retrieve all applications for a specific job posting.

Query Parameters

status (optional): Filter by application status (pending, reviewed, accepted, rejected)

GET /api/jobs/507f1f77bcf86cd799439011/applications?status=pending

PUT /api/jobs/{id}/view

Increment the view count for a job posting (for analytics).

PUT /api/jobs/507f1f77bcf86cd799439011/view

PUT /api/jobs/{id}

Update job posting details (excluding system fields like createdAt, applications, views).

{
  "title": "Updated Job Title",
  "description": "Updated job description",
  "status": "active",
  "featured": true,
  "compensation": {
    "type": "hourly",
    "amount": 50,
    "currency": "USD"
  }
}

DELETE /api/jobs/{id}

Permanently delete a job posting.

DELETE /api/jobs/507f1f77bcf86cd799439011

Statistics

Comprehensive platform analytics and statistical reporting for campaigns, users, and system performance.

GET /api/statistics/overview

Get high-level platform statistics including counts of campaigns, users, applications, and jobs.

Example Response

{
  "success": true,
  "data": {
    "campaigns": {
      "total": 145,
      "active": 34,
      "completed": 89,
      "cancelled": 22
    },
    "users": {
      "total": 2847,
      "creators": 2156,
      "brands": 691,
      "active": 2634
    },
    "applications": {
      "total": 1456,
      "pending": 234,
      "approved": 987,
      "rejected": 235
    },
    "jobs": {
      "total": 89,
      "open": 23,
      "closed": 66
    }
  },
  "generatedAt": "2024-07-09T12:00:00.000Z"
}

GET /api/statistics/campaigns/{id}

Get detailed statistics for a specific campaign including applications and performance metrics.

GET /api/statistics/campaigns/507f1f77bcf86cd799439011

GET /api/statistics/users/{id}

Get user activity statistics and performance metrics.

GET /api/statistics/users/507f1f77bcf86cd799439012

GET /api/statistics/trends

Get platform trends and time-series data for analytics dashboards.

Query Parameters

period: Time period (day, week, month, year)
metric: Specific metric to track
startDate: Start date for time range
endDate: End date for time range

GET /api/statistics/trends?period=month&metric=campaigns&startDate=2024-01-01

Session Management

Manage user sessions, authentication state, and API versioning.

GET /api/sessions/current

Get information about the current user session.

Example Response

{
  "sessionId": "sess_abc123def456",
  "userId": "507f1f77bcf86cd799439012",
  "createdAt": "2024-07-09T10:00:00.000Z",
  "lastAccessed": "2024-07-09T12:30:00.000Z",
  "maxAge": 3600000,
  "data": {
    "loginTime": "2024-07-09T10:00:00.000Z",
    "userRole": "creator"
  },
  "apiVersion": "v1"
}

POST /api/sessions/login

Create a new session for user authentication.

Required Fields

userId: ID of the user to create session for

{
  "userId": "507f1f77bcf86cd799439012",
  "userData": {
    "userRole": "creator",
    "preferences": {"theme": "dark"}
  }
}

POST /api/sessions/logout

Destroy the current session and clear authentication state.

POST /api/sessions/logout

PUT /api/sessions/data

Update session data with new key-value pairs.

{
  "theme": "light",
  "language": "en",
  "lastVisitedPage": "/campaigns"
}

DELETE /api/sessions/data/{key}

Remove a specific key from session data.

DELETE /api/sessions/data/theme

Search & Filtering

The Crowdswell API provides powerful search capabilities across all resources with support for full-text search, advanced filtering, sorting, and autocomplete suggestions.

POST /api/search/{collection}

Universal search endpoint supporting full-text search, filtering, and faceting.

Supported Collections

Core Collections

users, campaigns, creators, brands, jobs, events

Extended Collections

mediaplans, applications, placements, tasks

Request Body

{
  "query": "fashion summer",
  "filters": {
    "status": "active",
    "category": "fashion",
    "budget": { "$gte": 1000, "$lte": 10000 },
    "createdAt": { "$gte": "2024-01-01" }
  },
  "sort": {
    "budget": -1,
    "createdAt": -1
  },
  "page": 1,
  "limit": 20,
  "facets": ["category", "status", "budget_range"],
  "highlight": true,
  "fuzzy": true
}

Search Features

Feature	Description	Example
Full-text Search	Search across multiple text fields	`"fashion influencer"`
Filtering	MongoDB-style query filters	`{"status": "active"}`
Faceting	Aggregated counts by field values	`["category", "status"]`
Highlighting	Highlight search terms in results	`"highlight": true`
Fuzzy Matching	Handle typos and variations	`"fuzzy": true`

GET /api/search/suggest/{collection}/{field}

Get autocomplete suggestions for search queries.

Example Request

curl "https://ostendov3.nucleotto.com/api/search/suggest/campaigns/title?q=fash&limit=5"

Example Response

{
  "success": true,
  "data": {
    "suggestions": [
      "Fashion Forward Campaign",
      "Fashion Week Collaboration", 
      "Fashion Influencer Partnership"
    ],
    "query": "fash",
    "field": "title",
    "collection": "campaigns"
  }
}

File Management

Comprehensive file upload and management system with automatic processing, thumbnail generation, and metadata extraction.

POST /api/files/upload

Upload a single file with optional processing options.

Form Data

Field	Type	Required	Description
`file`	file	Yes	The file to upload
`generateThumbnails`	boolean	No	Generate image thumbnails
`compressImages`	boolean	No	Compress images
`extractMetadata`	boolean	No	Extract file metadata

Example Request

curl -X POST "https://ostendov3.nucleotto.com/api/files/upload" \ -F "[email protected]" \ -F "generateThumbnails=true" \ -F "compressImages=true"

File Processing Features

🖼️ Thumbnail Generation

Automatic thumbnail creation in multiple sizes (small, medium, large)

📊 Metadata Extraction

Extract EXIF data, dimensions, duration, and other metadata

🗜️ Image Compression

Reduce file size while maintaining visual quality

🔍 File Validation

Virus scanning and file type validation

Analytics & Reporting

Real-time analytics and comprehensive reporting system for tracking API usage, performance metrics, and business insights.

GET /api/analytics/overview

Get high-level analytics overview with key metrics.

Example Response

{
  "success": true,
  "data": {
    "requests": {
      "total": 145832,
      "today": 2847,
      "thisWeek": 18394,
      "thisMonth": 87263
    },
    "performance": {
      "averageResponseTime": 87,
      "uptime": 99.8,
      "errorRate": 0.02
    },
    "topEndpoints": [
      { "endpoint": "/api/campaigns", "requests": 12543 },
      { "endpoint": "/api/users", "requests": 9876 }
    ]
  }
}

GET /api/analytics/realtime

Get real-time metrics updated every minute.

Real-time Metrics

👥 Active Users

Currently active users on the platform

⚡ Requests/Minute

API requests in the last minute

📊 Response Time

Average response time across all endpoints

🚨 Error Count

Number of errors in the last minute

Bulk Operations

Efficient bulk operations for creating, updating, and deleting multiple records in a single request.

POST /api/bulk/{collection}/create

Create multiple records in a single operation.

Request Body

{ "records": [ { "name": "Creator 1", "email": "[email protected]", "userType": "creator" }, { "name": "Creator 2", "email": "[email protected]", "userType": "creator" } ], "options": { "validateAll": true, "continueOnError": false, "batchSize": 100 } }

Supported Operations

Operation	Endpoint	Description
Bulk Create	`POST /api/bulk/{collection}/create`	Create multiple records
Bulk Update	`PUT /api/bulk/{collection}/update`	Update multiple records
Bulk Delete	`DELETE /api/bulk/{collection}/delete`	Delete multiple records
Bulk Upsert	`POST /api/bulk/{collection}/upsert`	Create or update records
CSV Import	`POST /api/bulk/{collection}/csv-import`	Import from CSV file

Data Export/Import

Comprehensive data export and import functionality supporting JSON, CSV, and XML formats.

GET /api/export/{collection}

Export data in various formats with filtering options.

Supported Formats

📄 JSON

JavaScript Object Notation (default)

📊 CSV

Comma-Separated Values

🏷️ XML

Extensible Markup Language

Example Request

curl "https://ostendov3.nucleotto.com/api/export/campaigns?format=csv&filters={\"status\":\"active\"}" \
  -o campaigns-export.csv

POST /api/import/{collection}

Import data from JSON, CSV, or XML files.

Import Features

✅ Validation

Comprehensive data validation before import

🔄 Update Existing

Option to update existing records

📊 Progress Tracking

Real-time import progress and error reporting

⚡ Batch Processing

Efficient batch processing for large datasets

Caching

Redis-powered caching system for improved performance and reduced database load.

GET /api/cache/stats

Get cache performance statistics and metrics.

Example Response

{
  "success": true,
  "data": {
    "redis": {
      "connected": true,
      "uptime": 2847392,
      "totalKeys": 1243,
      "usedMemory": "15.2MB",
      "hitRate": 87.4
    },
    "cache": {
      "hits": 45632,
      "misses": 8976,
      "hitRatio": 0.836
    }
  }
}

DELETE /api/cache/clear

Clear cache by pattern.

{
  "pattern": "campaigns:*",
  "confirm": true
}

Media Plans

Create and manage comprehensive media planning and campaign strategies.

POST /api/mediaplans

Create a new media plan for campaign strategy.

Request Body

{
  "name": "Summer Campaign Media Plan",
  "campaignId": "campaign_id_here",
  "strategy": {
    "objectives": ["awareness", "engagement", "conversions"],
    "targetAudience": {
      "demographics": ["18-35", "female"],
      "interests": ["fashion", "lifestyle"],
      "platforms": ["instagram", "tiktok"]
    }
  },
  "timeline": {
    "startDate": "2024-07-01T00:00:00.000Z",
    "endDate": "2024-08-31T23:59:59.999Z"
  },
  "budget": {
    "total": 25000,
    "allocation": {
      "content_creation": 15000,
      "paid_promotion": 8000,
      "influencer_fees": 2000
    }
  }
}

📋 Strategy Planning

Define objectives, target audience, and campaign approach

📅 Timeline Management

Plan campaign phases and milestone tracking

💰 Budget Allocation

Track spending across different campaign elements

📊 Performance Tracking

Monitor media plan effectiveness and ROI

Error Handling

The Crowdswell API uses conventional HTTP response codes and provides detailed error information.

Error Response Format

{
  "success": false,
  "error": {
    "type": "ValidationError",
    "message": "Invalid request parameters",
    "code": "INVALID_PARAMETERS",
    "details": {
      "field": "email",
      "reason": "Invalid email format",
      "value": "invalid-email"
    }
  },
  "requestId": "req_6150d3c8e8b9a234567890ab"
}

Common Error Types

Error Type	Status Code	Description
ValidationError	400	Invalid request parameters or validation failures
NotFoundError	404	Requested resource doesn't exist
ConflictError	409	Resource already exists or constraint violation
RateLimitError	429	Too many requests, rate limit exceeded
ServerError	500	Internal server error

Rate Limits

To ensure fair usage and maintain service quality, the API implements rate limiting.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642507200
X-RateLimit-Window: 3600

Default Limits

Endpoint Type	Requests per Hour	Burst Limit
Read Operations	1000	50
Write Operations	500	25
Search Operations	200	10
File Uploads	100	5
Bulk Operations	50	2

SDKs & Libraries

Official and community SDKs for popular programming languages.

JavaScript/Node.js

npm install crowdswell-api

const CrowdswellAPI = require('crowdswell-api');

const client = new CrowdswellAPI({
  baseURL: 'https://ostendov3.nucleotto.com'
});

// List campaigns
const campaigns = await client.campaigns.list({
  status: 'active',
  limit: 20
});

// Search campaigns
const results = await client.search.campaigns({
  query: 'fashion summer',
  filters: { status: 'active' }
});

Python

pip install crowdswell-python

from crowdswell import CrowdswellAPI

client = CrowdswellAPI(
    base_url='https://ostendov3.nucleotto.com'
)

# List campaigns
campaigns = client.campaigns.list(status='active', limit=20)

# Search
results = client.search.campaigns(
    query='fashion summer',
    filters={'status': 'active'}
)

Webhooks (Coming Soon)

The Crowdswell API will support webhooks to notify your application when events occur.

Planned Event Types

Campaign Events

campaign.created, campaign.updated, campaign.completed

Application Events

application.submitted, application.approved, application.rejected

Content Events

placement.content_submitted, placement.metrics_updated

User Events

user.created, user.updated, user.deleted