🎉 Welcome to Creator Studio Documentation. Get started →
Developer
Overview

Developer Documentation

Welcome to the Creator Studio developer documentation. This guide provides technical details about the API architecture and available endpoints.

API Overview

API Structure

Creator Studio uses a context-aware API where organization context is automatically extracted from the authenticated user's token. This provides cleaner URLs and better security.

Base URL

https://[your-domain]/api/[resource]

Core API Endpoints

Content Management

  • /api/content - Unified content management (generations and schedules)
  • /api/content/schedules - Content scheduling operations
  • /api/content/multi-platform - Multi-platform generation
  • /api/content/intelligence - AI-powered content ideas
  • /api/content/optimize - Content optimization

Social Profiles

  • /api/profiles - Social account management
  • /api/profiles/:id/settings - Profile generation settings
  • /api/profiles/:id/effective-settings - Merged brand/profile settings
  • /api/profiles/:id/schedule-slots - Schedule slot management
  • /api/profiles/bulk - Bulk profile operations

Brand Management

  • /api/brands - Brand operations
  • /api/brands/:id/logo - Logo management
  • /api/brands/:id/profiles - Brand-profile associations
  • /api/brands/:id/reference-images - Reference image management
  • /api/brands/:id/settings - Brand generation settings

Media & Assets

  • /api/media - Media asset management
  • /api/media/upload - File uploads
  • /api/media/reference-images - Reference images
  • /api/media/thumbnails - Thumbnail management

Publishing & Scheduling

  • /api/posts/scheduled - Scheduled posts
  • /api/posts/queue - Publishing queue
  • /api/posts/publish - Direct publishing

Analytics & Monitoring

  • /api/analytics/overview - Analytics summary
  • /api/analytics/profiles - Profile performance
  • /api/analytics/content - Content metrics
  • /api/monitoring/errors - Error tracking

Other Endpoints

  • /api/tags - Content tagging
  • /api/events - Campaign/event management
  • /api/batch/* - Batch operations
  • /api/oauth/* - OAuth integrations

Authentication

Creator Studio uses Clerk for authentication. All API endpoints require authentication, and the organization context is automatically extracted from the authenticated user's token.

Authentication Headers

const headers = {
  'Authorization': 'Bearer YOUR_AUTH_TOKEN',
  'Content-Type': 'application/json'
};

Key Features:

  • Organization ID extracted from auth token automatically
  • No need to pass orgId in URLs or request bodies
  • Better security through token-based organization verification
  • All endpoints are scoped to the authenticated user's organization

Webhooks & Real-time Updates

Creator Studio provides real-time updates through Pusher:

Real-time Events

  • Pusher Integration for live updates
  • Event Types:
    • Content generation progress
    • Approval workflow updates
    • Publishing status changes
    • Video generation progress

System Webhooks

The following webhooks are used for platform integrations:

  • /webhook/clerk - User and organization events
  • /webhook/billing - Subscription events
  • /webhook/replicate - AI generation completion
  • /webhook/instagram - Instagram API callbacks

Rate Limiting

API endpoints are rate-limited to ensure fair usage:

  • Authenticated requests: 100 requests per minute
  • Content generation: 10 requests per minute
  • Batch operations: 5 requests per minute

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1641024000

API Client Helper

The application includes a centralized API helper file that provides type-safe endpoint definitions. This ensures consistency across the application and makes it easy to discover available endpoints.

Using the API Helper

import { api } from '@/lib/api-helpers';
 
// Example: Fetch profiles
fetch(api.profiles.list());
 
// Example: Get specific content
fetch(api.content.get(contentId));
 
// Example: Upload media with filename
fetch(api.media.uploadWithFilename('image.jpg'));

The API helper provides:

  • Type safety with TypeScript
  • Consistent URL patterns
  • Easy refactoring when endpoints change
  • IDE autocomplete support

Architecture

Tech Stack

Frontend

  • Next.js 15 (App Router with i18n)
  • React 18
  • TypeScript
  • Tailwind CSS
  • shadcn/ui components

Backend

  • Node.js
  • PostgreSQL (Neon)
  • Drizzle ORM

Infrastructure

  • Vercel Blob (media storage)
  • GCP (thumbnail extraction)
  • OpenAI & Replicate (AI generation)
  • Pusher (real-time updates)

Authentication

  • Clerk (user & organization management)
  • OAuth 2.0 (social platform connections)

Key Features

  • Context-aware API: Organization context from auth tokens
  • Domain-driven design: Services organized by business domain
  • Real-time updates: Pusher for live notifications
  • Batch operations: Efficient bulk processing
  • Content intelligence: AI-powered content generation and optimization

API Examples

Create Content

POST /api/content
{
  "socialProfileId": "uuid",
  "platform": "instagram",
  "postType": "reel",
  "media": "video",
  "dimensions": "9:16",
  "prompt": "Create an engaging reel about our product",
  "generationMode": "prompt_based"
}
 
// Response
{
  "id": "content-id",
  "status": "generating",
  "platform": "instagram",
  "postType": "reel",
  "socialProfileId": "uuid"
}

Schedule Content

POST /api/content/schedules
{
  "socialProfileId": "uuid",
  "scheduledDate": "2025-01-15",
  "task": "Create Instagram post about product launch",
  "generationMode": "prompt_based",
  "platform": "instagram",
  "postType": "feed",
  "media": "image",
  "dimensions": "1:1"
}

Get Profile Analytics

GET /api/analytics/profiles?profileId=uuid&period=30d
 
// Response
{
  "profileId": "uuid",
  "period": "30d",
  "metrics": {
    "totalContent": 45,
    "publishedContent": 38,
    "scheduledContent": 7,
    "engagement": {
      "total": 12500,
      "average": 329
    }
  }
}

Error Handling

Error Response Format

{
  "error": "Error message",
  "details": {
    // Additional error context
  }
}

HTTP Status Codes

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

Common Query Parameters

Most list endpoints support these standard parameters:

  • limit - Results per page (default: 20, max: 100)
  • offset - Number of results to skip
  • page - Page number (alternative to offset)
  • sort - Sort field with direction (e.g., created_at:desc)
  • q or search - Search query
  • date_from - Start date filter (ISO 8601)
  • date_to - End date filter (ISO 8601)

Best Practices

API Usage

  1. Use pagination for list endpoints to improve performance
  2. Cache responses where appropriate
  3. Handle errors gracefully with exponential backoff
  4. Use Pusher events for real-time updates instead of polling
  5. Batch operations when working with multiple items
  6. Include proper authentication in all requests

Response Formats

Success Response:

{
  "data": { /* resource data */ }
}

List Response with Pagination:

{
  "data": [ /* array of resources */ ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 100,
    "hasNext": true,
    "hasPrev": false
  }
}

Support

Getting Help

Additional Resources

Important Notes

  • This application uses Next.js App Router with internationalization support
  • API routes are internally scoped with locale parameters but should be called without locale prefixes from the client
  • All endpoints automatically handle organization context from authentication tokens
  • The application follows domain-driven design principles with services organized by business domain
CSV ImportAPI Reference