Integration Guide

Everything you need to integrate Castopia into your platform or workflow.

AI Integration Builder

Answer a few questions and get a complete prompt you can paste into Cursor, ChatGPT, or Claude to build your integration automatically.

What kind of integration?

Step-by-Step Setup

Follow these steps to get your integration running.

Create an Account & Get Your API Key

Apply for Partner Access (if integrating customers)

Go to Settings → Partner API and submit your application. We'll activate it quickly. Skip this if using individual mode.

Register Your First Customer

javascript

const API_KEY = "sk_live_...";
const BASE = "https://app.castopia.ai";

// Register a customer
const customer = await fetch(`${BASE}/api/v1/customers`, {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    externalId: "tutor-sarah-123",
    name: "Professor Sarah",
    email: "sarah@example.com",
    websiteUrl: "https://heyaviya.com/tutors/sarah",
  }),
}).then(r => r.json());

console.log("Customer ID:", customer.id);

Submit Content for Marketing

One call generates video clips, promotional flyers, and social media posts:

javascript

// Submit content for marketing
const result = await fetch(
  `${BASE}/api/v1/customers/${customer.id}/market`,
  {
    method: "POST",
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      content: {
        url: "https://heyaviya.com/courses/calc-101/welcome",
        title: "Calculus 101 - Welcome Video",
        type: "video",
      },
      platforms: ["instagram", "tiktok", "facebook"],
      options: {
        generateClip: true,
        generateFlyer: true,
        generateSocialPosts: true,
      },
    }),
  }
).then(r => r.json());

console.log("Campaign:", result.campaignId);
console.log("Status:", result.status); // "processing"

Embed the Analytics Dashboard

Get a themed embed token and display it in your product:

html

<!-- Get token from POST /api/v1/customers/:id/embed-token -->
<iframe
  src="https://app.castopia.ai/embed/dashboard?token=YOUR_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
  style="border-radius: 8px; border: 1px solid #e5e7eb;"
></iframe>

Set Up Webhooks (Optional)

Receive real-time notifications when marketing events occur:

javascript

// Configure your webhook URL
await fetch("https://app.castopia.ai/api/v1/webhooks", {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    webhookUrl: "https://api.yourapp.com/webhooks/castopia"
  })
});

// Events you'll receive:
// - customer.created
// - marketing_run.started
// - marketing_run.completed
// - content.generated
// - campaign.updated

Example: Tutoring Platform (HeyAviya)

HeyAviya is a tutoring marketplace. Tutors have courses with welcome videos. When a tutor opts in to marketing, HeyAviya calls our API to automatically promote their courses across all social platforms.

Flow

1. Tutor enables “Auto Marketing” toggle on their dashboard
2. HeyAviya calls POST /api/v1/customers with the tutor's info
3. When a course is published, HeyAviya calls POST /api/v1/customers/:id/market with the welcome video
4. Castopia generates clips, flyers, social posts — sends webhooks on completion
5. Tutor sees marketing analytics via embedded dashboard on their HeyAviya profile

Example: Individual Content Creator

A YouTuber wants to automatically generate Instagram Reels, TikToks, and promotional flyers every time they publish a new video.

Flow

1. Creator gets an API key from Settings → API Keys
2. Sets up a simple script (or Zapier/n8n workflow) that calls POST /api/v1/market with each new video
3. Castopia generates clips, flyers, and social posts automatically
4. Creator checks progress via GET /api/v1/campaigns or the Castopia dashboard