Back to Docs
API Reference

API & Webhooks

Integrate MCPity Motion into your workflow with our REST API and real-time webhooks.

Authentication
Webhook Events
API Endpoints

Authentication

All API requests require authentication using a Bearer token. You can obtain your access token from the Supabase auth session.

Request Header
Authorization: Bearer your_access_token

Security Note

Never expose your access tokens in client-side code. Use server-side API calls or Supabase's built-in RLS policies for secure data access.

Webhook Events

Subscribe to webhook events to receive real-time notifications when actions occur in your account.

challenge.created

A new challenge was created

Example Payload
{
  "challenge_id": "ch_123",
  "title": "Summer Remix Challenge",
  "status": "draft"
}
challenge.published

A challenge went live

Example Payload
{
  "challenge_id": "ch_123",
  "title": "Summer Remix Challenge",
  "status": "live",
  "end_at": "2024-12-31T23:59:59Z"
}
entry.submitted

A new entry was submitted to a challenge

Example Payload
{
  "entry_id": "ent_456",
  "challenge_id": "ch_123",
  "youtube_url": "https://youtube.com/...",
  "submitted_at": "2024-01-15T10:30:00Z"
}
entry.approved

An entry was approved by the host

Example Payload
{
  "entry_id": "ent_456",
  "challenge_id": "ch_123",
  "approved_at": "2024-01-15T12:00:00Z"
}
winner.selected

A winner was selected for a challenge

Example Payload
{
  "entry_id": "ent_456",
  "challenge_id": "ch_123",
  "winner_handle": "@artist123",
  "selected_at": "2024-01-20T15:00:00Z"
}
drop.submission

A fan submitted a Drop form

Example Payload
{
  "drop_id": "drp_123",
  "email": "fan@example.com",
  "submitted_at": "2024-01-15T10:30:00Z"
}
mixtape.claimed

A fan claimed a free mixtape

Example Payload
{
  "drop_id": "drp_123",
  "claim_id": "clm_456",
  "email": "fan@example.com",
  "claimed_at": "2024-01-15T10:30:00Z"
}

Webhook Signature Verification

Always verify webhook signatures to ensure requests are from MCPity Motion.

// Verify webhook signature (Node.js)
import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-mcpity-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process the webhook
  const { event, data } = req.body as { event: string; data: unknown };
  console.log(`Received ${event}:`, data);
  
  res.status(200).json({ received: true });
});

API Endpoints

Motion Projects

Manage Motion Studio projects programmatically

GET/api/motion/projects

List all Motion projects for your account

Auth: Bearer Token

Query Parameters:

status(string)Filter: draft, rendering, complete
limit(number)Max results (default: 20)
GET/api/motion/projects/:id

Get project details including scene plan

Auth: Bearer Token
GET/api/motion/projects/:id/export

Get export URLs for a completed project

Auth: Bearer Token

Motion Exports

Manage render exports and download links

GET/api/motion/exports

List all exports for your account

Auth: Bearer Token

Query Parameters:

status(string)Filter: queued, rendering, complete, failed
limit(number)Max results (default: 50)
GET/api/motion/exports/:id

Get export status and download URL

Auth: Bearer Token

Webhooks

Receive real-time notifications for events in your account

POST/api/webhooks/configure

Configure webhook endpoints for your account

Auth: Bearer Token

Request Body:

{
  "url": "https://your-domain.com/webhook",
  "events": [
    "challenge.created",
    "entry.submitted",
    "winner.selected"
  ],
  "secret": "whsec_..."
}
GET/api/webhooks/deliveries

List recent webhook delivery attempts

Auth: Bearer Token

Query Parameters:

limit(number)Max results (default: 50)
status(string)Filter by status: success, failed, pending
POST/api/webhooks/test

Send a test webhook to verify your endpoint

Auth: Bearer Token

Request Body:

{
  "endpoint_id": "wh_endpoint_123",
  "event_type": "test.ping"
}

Profile

Manage your public profile and analytics

GET/api/profile

Get your profile details

Auth: Bearer Token
GET/api/profile/analytics

Get profile analytics (views, clicks, engagement)

Auth: Bearer Token

Query Parameters:

start_date(string)ISO date (YYYY-MM-DD)
end_date(string)ISO date (YYYY-MM-DD)

Code Examples

Using Supabase Client (Recommended)

// Using Supabase client (recommended)
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
);

// Fetch challenges
const { data: challenges, error } = await supabase
  .from('challenge')
  .select('*')
  .eq('status', 'live')
  .order('created_at', { ascending: false });

// Subscribe to real-time updates
supabase
  .channel('challenges')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'challenge_entries' },
    (payload) => console.log('New entry:', payload.new)
  )
  .subscribe();

Fetch API Example

// Fetch challenges (JavaScript)
const response = await fetch('https://api.motion.mcpity.com/api/challenges', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const { challenges } = await response.json();
console.log(challenges);

Rate Limits

100

Requests per minute

1,000

Requests per hour

10,000

Requests per day

Rate limits are applied per user. If you need higher limits, contact support.

Need help with integration?

Check out our webhook documentation or reach out to our support team for assistance.

Configure WebhooksContact Support