RawUGC API

Procedural knowledge for agents to call the RawUGC API. All requests require an API key from the RawUGC dashboard, passed via environment variable.

Authentication

• Environment variable: Read the API key from RAWUGC_API_KEY. The key is created in the RawUGC dashboard and must be kept secret; do not hardcode or log it.
• Header: Send on every request: Authorization: Bearer \x3Cvalue of RAWUGC_API_KEY>.
• If RAWUGC_API_KEY is missing or empty, inform the user they must set it and obtain a key from the RawUGC dashboard.

Base URL

• Production: https://rawugc.com/api/v1
• All paths below are relative to this base.

API Versioning

RawUGC uses date-based API versioning. The current latest version is 2026-03-06.

• RawUGC-Version request header: Override the version per-request (recommended).
• API key pinned version: Set when creating the key in the dashboard.
• Fallback: Latest version (2026-03-06) if neither is set.

Always send RawUGC-Version: 2026-03-06 in requests to ensure consistent behavior.

Video Generation

POST /videos/generate

Initiate video generation.

Request body (JSON):

Response (201): videoId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /videos/:videoId

Get video status. Returns videoId, status, model, prompt, creditsUsed, url (when completed), createdAt, completedAt, failCode, failMessage, versions (edit history array).

GET /videos

List videos. Query: status, limit (1-100, default 50), page. Returns videos array + pagination.

POST /videos/captions

Add styled captions to a completed video. Costs 1 credit.

Response (200): videoId, url, version, operation, creditsUsed.

POST /videos/overlay

Add text overlay to a completed video.

Response (200): videoId, url, version, operation, creditsUsed.

Image Generation

POST /images/generate

Generate AI images using Nano Banana models. Async -- poll GET /images/:imageId.

Response (201): imageId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /images/:imageId

Get image status. Returns imageId, status, model, prompt, url (when completed), imageSize, resolution, outputFormat, creditsUsed, createdAt, completedAt, failCode, failMessage.

GET /images

List images. Query: status, limit (1-100, default 20), page. Returns images array + pagination.

Music Generation

POST /music/generate

Generate AI music using Suno models. 3 credits per generation. Async -- poll GET /music/:musicId.

Response (201): musicId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /music/:musicId

Get music status. Returns musicId, status, model, prompt, audioUrl (when completed), albumArtUrl, duration, title, creditsUsed, createdAt, completedAt, failCode, failMessage.

GET /music

List music tracks. Query: status, limit (1-100, default 20), page. Returns tracks array + pagination.

Upload

POST /upload

Upload a video or image file. Returns a URL for use in generation requests (imageUrls, videoUrls) or analyze-video. Max 100MB.

Request: multipart/form-data with file field. Accepted types: video/mp4, video/quicktime, video/webm, image/png, image/jpeg, image/webp.

Response (200): url, contentType, size.

Characters

GET /characters

List all available AI characters (built-in + custom). Returns characters array, count, adminCount, userCount.

GET /characters/:characterId

Get a character by ID. Returns _id, username, displayName, description, videoPreviewUrl, type (admin/user), isActive, createdAt, updatedAt.

Personas (CRUD)

Personas define target audiences for content plan generation.

• GET /personas -- List all. Returns personas array + count.
• POST /personas -- Create. Body: name (required, max 200), description (required, max 5000). Returns id.
• GET /personas/:personaId -- Get one.
• PATCH /personas/:personaId -- Update. Body: name, description (both optional).
• DELETE /personas/:personaId -- Delete.

PersonaResponse: _id, organizationId, name, description, createdAt, updatedAt.

Messaging (CRUD)

Brand/positioning messaging templates.

• GET /messaging -- List all. Returns messages array + count.
• POST /messaging -- Create. Body: name (required, max 200), body (required, max 5000). Returns id.
• GET /messaging/:messageId -- Get one.
• PATCH /messaging/:messageId -- Update. Body: name, body (both optional).
• DELETE /messaging/:messageId -- Delete.

MessagingResponse: _id, organizationId, name, body, createdAt, updatedAt.

Products (CRUD)

Products for video generation.

• GET /products -- List all. Returns products array + count.
• POST /products -- Create. Body: name (required, max 200), photos (required, URL array), description (max 1000), messaging (max 5000). Returns id.
• GET /products/:productId -- Get one.
• PATCH /products/:productId -- Update. Body: name, description, photos, messaging (all optional).
• DELETE /products/:productId -- Delete.

ProductResponse: _id, name, description, photos, messaging, createdAt, updatedAt.

Styles (CRUD)

Video/image creative styles with optional prompt templates.

• GET /styles -- List all (built-in + custom). Query: type (video/image). Returns styles array + count.
• POST /styles -- Create. Body: name (required, max 200), description (max 1000), type (video/image), aspectRatio (portrait/landscape/square), promptTemplate (max 5000, supports {productName}, {messaging}, {character} placeholders). Returns id.
• GET /styles/:styleId -- Get one.
• PATCH /styles/:styleId -- Update. All fields optional.
• DELETE /styles/:styleId -- Delete.

StyleResponse: _id, name, description, type, aspectRatio, styleId, promptTemplate, isAdmin, isStandard.

Social Scheduling

GET /social/accounts

List connected social accounts (max 3 per org). Returns accounts array + count. Each account: accountId, platform (tiktok/instagram/youtube), username, displayName, profilePicture, isActive.

POST /social/accounts

Sync connected accounts from the scheduling provider. Returns { success: boolean }.

DELETE /social/accounts/:accountId

Disconnect a social account. Returns { success: boolean }.

POST /social/posts

Schedule, draft, or immediately publish a video to social media.

Response (201): SocialPost object.

GET /social/posts

List posts. Query: fromDate (ms), toDate (ms), includeDrafts (boolean). Returns posts array + count.

GET /social/posts/:postId

Get a post.

PATCH /social/posts/:postId

Update a post. Body: content, scheduledFor, timezone, accountIds (at least one field required).

DELETE /social/posts/:postId

Delete a post. Returns { success: boolean }.

POST /social/posts/:postId/reschedule

Reschedule a post. Body: scheduledFor (required, ms), timezone.

POST /social/posts/:postId/publish

Immediately publish a draft post.

SocialPost: postId, platforms, status (draft/scheduled/published/failed), scheduledFor, timezone, content, videoUrl, createdAt, publishedAt.

Viral Library

GET /viral-library/videos/:videoId

Get a viral library video with full AI analysis (hooks, keyframes, performance insights). Returns ViralLibraryVideo.

GET /viral-library/search

Semantic search across analyzed videos. Query: q (required, natural language), limit (1-50, default 20). Returns results (array of { video, score }), query, total.

Research

POST /scrape-tiktok

Scrape TikTok videos. Costs 3 credits.

Response (200): scrapeId (use with content-plans), count, videos (array with id, url, author, description, stats, duration, hashtags, thumbnail, videoUrl).

POST /content-plans

Generate a content plan from scraped videos. Costs 3 credits.

Response (200): planId, scrapeId, brief, topWins, gapsToTest, blueprints (array with category, strategy, evidence, contentIdeas).

GET /content-plans

List all content plans. Returns plans array + count.

POST /analyze-video

Analyze any video URL (social links or direct URLs). Costs 1 credit. Max 150MB.

Response (200): summary, hook, keyframes (array with timestamp, type, description, visual, audio, text), durationSeconds, tags, whyItPerformed, attributesToCopy, hooksToTest.

Errors

All error responses use RFC 7807 Problem Details (JSON): type, title, status, detail, instance, errors.

Rate Limits

• API Key: 10 req/min. Session: 20 req/min.
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix timestamp).

Workflow: Generate then poll

1. Generate: POST to the generation endpoint. Note the returned ID (videoId/imageId/musicId).
2. Poll: GET the status endpoint periodically (10-30s). Use exponential backoff.
3. Finish: When status === 'completed', use the result URL. When failed, surface error to user.
4. Edit (video only): POST to /videos/captions or /videos/overlay.

For full request/response shapes, see reference.md.