Current public API surface

Pamba API Docs

Build agent-driven workflows for AI avatar videos, TikTok research, video generation, scheduling, warming, and analytics with workspace-scoped API keys.

Authentication

Agents authenticate with X-API-Key. JWT callers include X-Workspace-Id on workspace routes.

Workspace-Scoped

API keys are tied to one workspace, so agents can create content, manage avatars, schedule posts, and pull analytics for that workspace.

Base URL

Use https://api.pamba.app. All content production routes require authentication.

Bulk project creation accepts date-only scheduling, such as 2026-05-18. Single post scheduling accepts date-only or ISO 8601 with timezone.

Credit Usage

Generation features are credit-metered: video clips, avatar photos, scene images, voices, and hook purchases. A user's very first avatar is free — its photos, scenes, and basic voice are not charged (premium voice still is). Fetch the current price list from GET /usage/pricing (public, no auth).

AI clip generation

POST /projects/{projectId}/generate-clip-videos, plus automated pipelines started from bulk project creation or automation restart/resume.

50 credits x generated video seconds. Credits are reserved for requested duration, then only successful generated clip seconds are charged.

Avatar photo generation

POST /avatars/generations, POST /avatars/projects/{projectId}/chat/async whenever the avatar agent generates or edits an appearance image, and the avatar wizard appearance pass.

15 credits per generated image. Failed generations are not charged.

Scene generation

POST /avatars/projects/{projectId}/selected-avatar/starting-frames and .../starting-frames/generations, plus starter scenes auto-populated by avatar creation and the avatar wizard.

15 credits per generated image. Bulk jobs reserve avatars x references x results upfront and charge only successfully generated images; uploads of your own frames are free.

Voice generation

Avatar creation/update chat whenever a new voice is designed, POST /avatars/projects/raw, PATCH /avatars/projects/{projectId} when selecting an avatar without a voice, and keeping a basic voice in the avatar wizard. Wizard voice previews are free to audition.

100 credits per voice. Charged once per created voice; reusing an avatar's existing voice is free.

Premium voice generation

Avatar chat with video_model_based_voice_creation, the toggle-only premium voice regeneration, and premium options in the avatar wizard (charged per clone generated).

1500 credits per voice clone. Covers the video-model speaking clips the voice is cloned from; the interim designed voice it replaces is not charged.

Hook video purchase

POST /hooks/purchase.

200 credits per hook. Already-purchased hooks are not re-charged.

Project creation, idea/script work, TikTok research/analytics, frame uploads and management, scheduling, warming, rendering existing edits, and editor-state saves are not separately credit-metered in the public API today. Metered endpoints respond 402 { error, remaining_credits, required_credits } when the balance is too low, and failed operations are never charged. Use GET /user to inspect subscription state and credit totals/usage.

What Agents Can Do

Track competitor accounts, filter their best videos, create ideas, remix scripts, and start projects.

Bulk-create fully automated projects that generate clips, render, schedule, and post.

Manually drive a project through concept, clip generation, selected takes, render, and scheduling.

Configure avatar warming and monitor session status.

Pull TikTok analytics dashboards, tracked account metrics, and per-video history.

Public Endpoint Reference

Account

Read caller profile, subscription state, and credit totals.

GET/user

Current user profile, subscription state, and credit totals/usage.

Authentication

X-API-Key or JWT. JWT callers do not need X-Workspace-Id on this bootstrap route.

Request

No body.

Response

200 { total_paid_monthly_credits, used_paid_monthly_credits, total_coupon_credits, used_coupon_credits, subscribed_product_name, subscription_status, email, email_verified, success, message }

Ideas and Scripts

Create content concepts, remix scripts, and link avatars. To start a project from a script, pass the script to POST /projects.

GET/ideas

List ideas with pagination, filters, sorting, and archived state.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query page, page_size, sort_by, sort_direction, archived, min_views, max_views, min_views_per_follower, max_views_per_follower, min_engagement_rate, max_engagement_rate, days_lookback, phone_number, search.

Response

200 { ideas: Idea[], page, page_size }; Idea includes id, title, notes, status, analyzed_video, scripts, avatars, video_projects, archived_at, created_at.
POST/ideas

Bulk-create ideas from titles, notes, and TikTok URLs.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "ideas": [{ "title"?, "tiktok_video_url"?, "notes"? }] }.

Response

201 { idea_ids: string[] }.

Example

curl -X POST https://api.pamba.app/ideas \
  -H "X-API-Key: $PAMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ideas": [{ "title": "Before/after plumbing POV", "notes": "Make it punchy" }] }'
PUT/ideas

Bulk-update ideas.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "ideas": [{ "idea_id": UUID, "notes"?, "tiktok_video_url"?, "archived"? }] }.

Response

200 { updated_count: number }.
PUT/ideas/{id}

Update notes, TikTok URL, or archived state for one idea.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "notes"?, "tiktok_video_url"?, "archived"? }.

Response

200 { success: true }.
POST/ideas/{id}/branch

Branch an idea into a new variant.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "new_title": string, "notes"?: string }.

Response

201 { idea_id: UUID }.
POST/ideas/{id}/avatars

Attach avatars to an idea.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "avatar_project_ids": UUID[] }.

Response

200 { success: true }.
DELETE/ideas/{id}/avatars

Remove avatars from an idea.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "avatar_project_ids": UUID[] }.

Response

200 { success: true }.
POST/ideas/scripts

Create a script for an idea.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "idea_id": UUID, "content": string }.

Response

201 { script_id: UUID }.
POST/ideas/scripts/remix

Generate script variations from an idea.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "idea_id": UUID, "custom_prompt"?: string }.

Response

201 { script_id: UUID }.
PUT/ideas/scripts/{id}

Update script content.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "content": string }.

Response

200 { success: true }.
DELETE/ideas/scripts/{id}

Delete a script.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; no body.

Response

200 { success: true }.
POST/ideas/scripts/{id}/avatars

Attach avatars to a script.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "avatar_project_ids": UUID[] }.

Response

200 { success: true }.
DELETE/ideas/scripts/{id}/avatars

Remove avatars from a script.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { id: UUID }; JSON body { "avatar_project_ids": UUID[] }.

Response

200 { success: true }.

TikTok Research and Analytics

Track accounts, inspect analyzed videos, and pull dashboard metrics.

POST/tiktok/tracked-accounts

Track TikTok usernames for research.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "usernames": string[] }.

Response

201 { account_ids: UUID[] }.

Example

curl -X POST https://api.pamba.app/tiktok/tracked-accounts \
  -H "X-API-Key: $PAMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "usernames": ["competitor_handle"] }'
GET/tiktok/tracked-accounts

List tracked accounts and avatar links.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

No body.

Response

200 { accounts: TrackedAccount[] }; includes username, follower_count, status, avatar_id, avatar_name, deactivation_reason.
DELETE/tiktok/tracked-accounts/{username}

Stop tracking an account.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { username: string }; no body.

Response

200 { success: true }; 409 if the account is linked to an avatar.
GET/tiktok/tracked-accounts/{username}/fetch-status

Check initial fetch status.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { username: string }; no body.

Response

200 { username, status }.
GET/tiktok/tracked-accounts/videos

List analyzed videos with username and performance filters.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query page, page_size, username, sort_by, sort_direction, min_views, max_views, min_views_per_follower, max_views_per_follower, min_engagement_rate, max_engagement_rate, days_lookback, search, include_research_accounts.

Response

200 { videos: TrackedVideo[], page, page_size }; video includes metrics, transcript, summary, idea_id, analysis fields.
GET/tiktok/tracked-accounts/{username}/views-per-day

Daily views, likes, comments, shares, and bookmarks.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { username }; query days 1-365, timezone.

Response

200 { username, days: [{ date, views, likes, comments, shares, bookmarks }] }.
GET/tiktok/tracked-accounts/{username}/metrics

Read account-level aggregates.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { username }; no body.

Response

200 aggregate metrics including video_count, total_views, average metrics, engagement rate, duration and posting cadence.
GET/tiktok/tracked-accounts/{username}/metrics-history

Per-video metric snapshots over time.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { username }; no body.

Response

200 { username, videos: [{ tiktok_video_id, title, description, author_username, snapshots[] }] }.
GET/tiktok/analytics/accounts

Accounts available in analytics.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

No body.

Response

200 { accounts: [{ username }] }.
GET/tiktok/analytics/dashboard

Fetch trends, top videos, recent videos, and comparisons.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query scope=all|research|avatar username, days 1-365, scopes comma-separated, timezone.

Response

200 dashboard data with current/previous totals, trend series, top videos, recent videos and optional comparison scopes.

Avatars and Starting Frames

Manage speaker personas and the images that keep videos visually consistent.

GET/avatars

List avatars by status or tag.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query avatar_status, tag.

Response

200 Avatar[]; includes id, project_id, name, status, tags, TikTok accounts, image/voice metadata and warming config.
POST/avatars/projects

Create a draft avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

No body.

Response

201 { project_id: UUID }.
POST/avatars/projects/raw

Create an avatar from multipart form data and a reference image.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

multipart/form-data: name, gender=MALE|FEMALE, image file; optional accent, base_appearance_description, adaptive_appearance_description, background_description, speaker_description.

Response

201 { avatar_id, project_id, name, gender, image_url, voice_id, voice_sample_url }; 402 { error, remaining_credits, required_credits } on insufficient credits.
GET/avatars/projects/{projectId}

Get an avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 avatar project details including selected avatar and generated candidates.
PATCH/avatars/projects/{projectId}

Select an avatar for an avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "selected_avatar_id": UUID }.

Response

200 OK; 402 { error, remaining_credits, required_credits } on insufficient credits.
DELETE/avatars/projects/{projectId}

Delete an avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

204 No Content.
PUT/avatars/projects/{projectId}/selected-avatar

Update selected avatar tags, TikTok usernames, status, and warming config.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "avatar_status"?, "tiktok_usernames"?, "tags"?, "enable_tiktok_warming"?, "warming_config"? }.

Response

200 OK.
PUT/avatars/projects/{projectId}/selected-avatar/tiktok-accounts/{username}

Update status for a linked TikTok account.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, username: string }; JSON body { "status": string }.

Response

200 OK.
POST/avatars/projects/{projectId}/chat

Chat with the avatar creator.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body either { "user_input": string } or { "structured_message": { name, gender, base_appearance_description, adaptive_appearance_description, background_description, voice_description } }.

Response

200 avatar chat response with generated avatar/project state.
GET/avatars/projects/{projectId}/selected-avatar/starting-frames

List selected-avatar scenes for an avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 AvatarFrame[]; frame has id, image_url, is_active, camera_style, tags, created_at, is_profile_image.
POST/avatars/projects/{projectId}/selected-avatar/starting-frames

Generate selected-avatar scenes from a prompt.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "prompt": string, "count": 1-10, "camera_style": string, "tags": string[] }.

Response

200 AvatarFrame[]; 402 { error, remaining_credits, required_credits } on insufficient credits.
POST/avatars/projects/{projectId}/selected-avatar/starting-frames/generations

Start a bulk scene generation job for the selected avatar.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "rows": [{ tiktok_url, camera_style, tags?, cover_url? }], "results_per_ref": 2-6 }.

Response

202 BulkGenerationJob { id, status, avatar_count, video_count, total_combinations, results_per_combo, completed_count, failed_count, created_at }; 402 { error, remaining_credits, required_credits } on insufficient credits.
POST/avatars/projects/{projectId}/selected-avatar/starting-frames/upload

Upload a selected-avatar scene image.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

multipart/form-data: image file, camera_style, optional comma-separated tags.

Response

200 AvatarFrame.
PUT/avatars/projects/{projectId}/selected-avatar/starting-frames/profile

Set a selected-avatar scene as profile image.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "frame_id": UUID }.

Response

200 OK.
PATCH/avatars/starting-frames/{frameId}

Update a frame's active state, camera style, or tags.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { frameId: UUID }; JSON body any of { "active": boolean, "camera_style": string, "tags": string[] }.

Response

200 OK.
DELETE/avatars/starting-frames/{frameId}

Delete one starting frame.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { frameId: UUID }; no body.

Response

204 No Content; 409 when deleting the profile image.
DELETE/avatars/starting-frames

Bulk-delete starting frames.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "frame_ids": UUID[] }.

Response

204 No Content.
GET/avatars/starting-frames/reference-frames

List reference frames, optionally by tag.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Optional query tag.

Response

200 ReferenceFrame[] for golden/reference frames.

Projects and Generation

Create fully automated batches or control each generation step manually.

POST/projects

Bulk-create projects, including fully automated projects.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "projects": [{ "selected_avatar_project_id": UUID, "script"?, "notes"?, "project_name"?, "is_fully_automated"?, "camera_style"?, "bullet_list"?, "scheduled_at"?, "video_description"?, "tiktok_username"?, "keep_tiktok_song"?, "only_create_draft"?, "reference_video_url"? }] }. The "script" is stored directly as the creative concept (deterministic script→clips split, no agent); required for is_fully_automated.

Response

201 { project_ids: UUID[] }.

Notes

If is_fully_automated is true, automation may later consume credits during clip generation.

Example

curl -X POST https://api.pamba.app/projects \
  -H "X-API-Key: $PAMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projects": [{
      "selected_avatar_project_id": "$AVATAR_PROJECT_ID",
      "project_name": "Plumber POV #1",
      "script": "Day in the life of a plumber. First call at 7am, a flooded basement. By noon I found a ring the customer lost years ago.",
      "is_fully_automated": true,
      "video_description": "Day in the life #plumbing",
      "tiktok_username": "plumber_pov",
      "scheduled_at": "2026-05-18"
    }]
  }'
POST/projects/create

Create one blank project for an avatar.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "selected_avatar_project_id": UUID }.

Response

200 Project { project, messages }.
GET/projects

List projects.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

No body.

Response

200 VideoProject[].
GET/projects/{projectId}

Get one project plus chat messages.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 Project { project, messages }.
PATCH/projects/{projectId}

Update metadata, states, notes, selected concept, reference URL, or automation config.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body any of { "project_name"?, "user_visibility"?, "posted_state"?, "user_review_state"?, "notes"?, "reference_video_url"?, "script_to_clips_config"?, "full_automation_configuration"? }.

Response

200 updated project.
PATCH/projects

Bulk-update project states and notes.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

JSON body { "updates": [{ "project_id": UUID, "user_visibility"?, "posted_state"?, "user_review_state"?, "notes"? }] }.

Response

200 { success: true }.
POST/projects/{projectId}/duplicate-shallow-concept

Duplicate a project's shallow concept.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

201 Project { project, messages }.
POST/projects/{projectId}/selected-creative-concept

Set speaker, background, script, and clips for the selected concept.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "speaker_description": string, "background_description": string, "clips"?, "script"?, "starting_frame_for_all_clips_url"?, "script_to_clips_config"? }.

Response

200 updated selected creative concept.
GET/projects/{projectId}/creative-concepts

List the project's creative concept version history, newest first.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 { "versions": [{ "id", "created_at", "is_selected", "speaker_description", "background_description", "script"?, "clips" }] } newest first.
POST/projects/{projectId}/creative-concepts/{conceptId}/select

Revert the project to a prior concept version.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, conceptId: UUID }; no body.

Response

200 on revert to that concept version; 404 when the concept doesn't belong to the project.
POST/projects/{projectId}/generate-starting-frames

Generate project-level starting frames.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "camera_style": string }.

Response

200 generated project-level starting frames.
POST/projects/{projectId}/upload-starting-frame

Upload a project-level starting frame image.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

multipart/form-data: image file plus optional metadata.

Response

200 uploaded starting frame.
DELETE/projects/{projectId}/starting-frames

Delete project-level starting frames.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "frame_ids": UUID[] }.

Response

200 OK.
POST/projects/{projectId}/edited-video

Upload a finished edited video.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

multipart/form-data with video file, or JSON/body containing an existing video URL depending on client flow.

Response

200 { "edited_video_url": string }.
POST/projects/{projectId}/generate-clip-videos

Generate selected clip indexes.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "clips_to_generate": [{ "index": number, "starting_frame_url"?: string }] }.

Response

200 generation result; 402 { error, remaining_credits, required_credits }; 429 { error, pending_count }.

Notes

Costs 50 credits x successfully generated video seconds.

Example

curl -X POST https://api.pamba.app/projects/$PROJECT_ID/generate-clip-videos \
  -H "X-API-Key: $PAMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "clips_to_generate": [{ "index": 0 }] }'
GET/projects/{projectId}/clips/{creativeConceptId}

Poll clip status for a creative concept.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, creativeConceptId: UUID }; no body.

Response

200 { clips: [{ clip_id, position, script, duration_seconds, video_url, generation_status }] }.
GET/projects/{projectId}/video-generations

Get all generation history for a project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 { clips: ClipVideoGenerationHistory[] }.
GET/projects/{projectId}/clips/{clipId}/video-generations

Get take history for one clip.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, clipId: UUID }; no body.

Response

200 VideoGeneration[] for the clip.
PATCH/projects/{projectId}/clips/{clipId}

Select a take for a clip.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, clipId: UUID }; JSON body { "selected_video_generation_id": UUID }.

Response

200 selection message, or 404 when clip/generation is not found.
POST/projects/{projectId}/render-full-video

Render the current project into a finished video.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 render result with output video URL/status.
POST/projects/{projectId}/resume-automation

Resume automation for a project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 { "message": "Automation resumed" }.
POST/projects/{projectId}/restart-automation

Restart automation for a project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 { "message": "Automation restarted" }.
POST/projects/{projectId}/automation/apply-clips

Apply generated clips in an automation pipeline.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 { "message": "Apply-clips pipeline started" }.
PATCH/projects/{projectId}/editor-state

Save editor state without rendering.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "editor_state": { "main_video_track": [{ "clip_id": UUID, "in_point"?: number, "out_point"?: number, "type"?: string }] } }.

Response

204 No Content.
POST/projects/{projectId}/render

Save editor state and start a background render job (202 + RenderJob; 409 if one is already running).

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body { "editor_state": { "main_video_track": [...] } }.

Response

202 RenderJob { id, project_id, status: "RUNNING", stitched_video_url, edited_video_url, error_message, created_at, completed_at } when a new render starts. 409 RenderJob when one is already running for the project (attach to it; renders are not replaced implicitly — cancel the running one first). Poll GET /projects/{projectId}/render-jobs/{jobId} (or .../render-jobs/latest) until status is COMPLETED, then read stitched_video_url/edited_video_url.
GET/projects/{projectId}/render-jobs/latest

Latest render job for the project (404 if never rendered).

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; no body.

Response

200 RenderJob for the project's most recent render, or 404 if it has never been rendered.
GET/projects/{projectId}/render-jobs/{jobId}

Poll a render job's status until COMPLETED.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, jobId: UUID }; no body.

Response

200 RenderJob with the current status and (when COMPLETED) the output URLs.
POST/projects/{projectId}/render-jobs/{jobId}/cancel

Cancel an in-flight render so a new one can be started.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID, jobId: UUID }; no body.

Response

200 RenderJob (status CANCELLED) when an in-flight render was cancelled; 409 if it already finished; 404 if no such job.
POST/projects/{projectId}/schedule

Schedule a project to TikTok with JSON or multipart upload.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; JSON body or multipart: { "tiktok_username": string, "caption": string, "scheduled_at": string, "privacy"?, "keep_tiktok_song"?, "only_create_draft"?, "video_url"?, "automate"?, "bullet_list"? }.

Response

200 ScheduledPost.
GET/projects/{projectId}/video-generation-updates

SSE stream for generation updates.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; SSE request.

Response

text/event-stream with video generation update events.
GET/projects/agent-state-updates

SSE stream for project automation lifecycle updates.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

SSE request; optional project filters may be added by the client.

Response

text/event-stream with project_id, creation_stage, activity_state, posted_state, user_review_state, automation_state, selected_creative_concept, scheduled_post.
GET/projects/public/{projectId}

Public project details for share links.

Authentication

Public. No authentication required.

Request

Path { projectId: UUID }; no body.

Response

200 Project { project, messages } for share links.

Streaming

Subscribe to project status events.

GET/stream/status/{projectId}

SSE status stream for project generation.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { projectId: UUID }; SSE request.

Response

text/event-stream status updates for project generation.

Scheduling and Warming

Operate TikTok post queues and pre-post account warming.

GET/devices/tiktok/posts/scheduled

List scheduled posts by page or date range.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query mode: page/page_size, or date range from, to, status, max. Optional username/project filters.

Response

200 { posts: ScheduledPost[], total, truncated? }.
GET/devices/tiktok/posts/{postId}

Get one scheduled post.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { postId: UUID }; no body.

Response

200 ScheduledPost.
PUT/devices/tiktok/posts/{postId}

Edit timing, caption, privacy, video URL, username, or failed-post dismissal.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { postId: UUID }; JSON body any of { "is_soft_deleted"?, "scheduled_at"?, "caption"?, "privacy"?, "keep_tiktok_song"?, "only_create_draft"?, "video_url"?, "tiktok_username"? }.

Response

200 ScheduledPost.
DELETE/devices/tiktok/posts/{postId}

Cancel a pending post. Optionally archive the project too.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { postId: UUID }; optional query archive_project=true.

Response

200 { success: true }.
POST/devices/tiktok/posts/{postId}/retry

Retry a failed post.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { postId: UUID }; no body.

Response

200 ScheduledPost.
GET/devices/tiktok/warming/config/avatar-projects/{avatarProjectId}

Read warming config for an avatar project.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { avatarProjectId: UUID }; no body.

Response

200 { enabled, status, total_minutes_daily_anchor, session_count_daily_anchor, search_terms, error_message }.
GET/devices/tiktok/warming/sessions

List warming sessions.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Query page/page_size/status/date filters depending on client flow.

Response

200 { sessions: WarmingSession[], total }.
GET/devices/tiktok/warming/sessions/{sessionId}

Get one warming session status/detail.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { sessionId: UUID }; no body.

Response

200 WarmingSession status/details.
DELETE/devices/tiktok/warming/sessions/{sessionId}

Cancel a pending warming session.

Authentication

X-API-Key, or JWT + X-Workspace-Id for workspace-scoped routes.

Request

Path { sessionId: UUID }; no body.

Response

200 { success: true }.

Billing

Stripe checkout/portal sessions and the public credit price list.

POST/billing/create-stripe-checkout-session

Create a Stripe checkout session.

Authentication

X-API-Key or JWT. JWT callers do not need X-Workspace-Id on this bootstrap route.

Request

JSON body { "price_id": string }.

Response

200 { "session_url": string }.
POST/billing/create-customer-portal-session

Create a Stripe customer portal session.

Authentication

X-API-Key or JWT. JWT callers do not need X-Workspace-Id on this bootstrap route.

Request

No body.

Response

200 { "portal_url": string }.
GET/usage/pricing

Public credit price list for all metered operations.

Authentication

Public. No authentication required.

Request

No body.

Response

200 { "video_generation_credits_per_second": 50, "photo_generation_credits_per_image": 15, "scene_generation_credits_per_image": 15, "basic_voice_generation_credits": 100, "premium_voice_generation_credits": 1500, "hook_video_purchase_credits": 200 }.

Notes

Values are the live backend constants; clients should read prices from here instead of hardcoding.

Fast Start

Create a project batch with an avatar and let automation handle generation, render, and scheduling.

curl -X POST https://api.pamba.app/projects \
  -H "X-API-Key: $PAMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projects": [{
      "selected_avatar_project_id": "$AVATAR_PROJECT_ID",
      "project_name": "Plumber POV #1",
      "script": "Day in the life of a plumber. First call at 7am, a flooded basement. By noon I found a ring the customer lost years ago.",
      "is_fully_automated": true,
      "video_description": "Day in the life #plumbing",
      "tiktok_username": "plumber_pov",
      "scheduled_at": "2026-05-18"
    }]
  }'