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. Most content production routes are currently alpha-gated.

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

Credit metering is currently limited to successful AI clip generation.

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.

Project creation, idea/script work, TikTok research/analytics, avatar and frame management, scheduling, warming, rendering existing edits, and editor-state saves are not separately credit-metered in the public API today. 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, is_alpha_user, success, message }

Ideas and Scripts

Create content concepts, remix scripts, link avatars, and start 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 }.
POST/ideas/{id}/create-video-project

Create a video project from an idea.

Authentication

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

Request

Path { id: UUID }; JSON body { "avatar_project_id": UUID }.

Response

201 { video_project_id: UUID, initial_message: string }.
POST/ideas/scripts/{id}/create-video-project

Turn a script into a Pamba video project.

Authentication

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

Request

Path { id: UUID }; JSON body { "avatar_project_id": UUID }.

Response

201 { video_project_id: UUID, initial_message: string }.

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 }.
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.
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[].
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 }.
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, "first_message"?, "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"? }] }.

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",
      "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"?, "selected_creative_concept_id"?, "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.
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 render the result.

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

200 render/apply-edits result.
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.

Chat and Streaming

Drive project chat and subscribe to project status events.

POST/chat/prompt

Send a multipart prompt to a project.

Authentication

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

Request

multipart/form-data with project_id, prompt/user input, and optional uploaded media.

Response

200 chat response/message payload.
GET/stream/status/{projectId}

SSE status stream for chat/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 chat/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

Create Stripe sessions for checkout and customer billing management.

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 }.

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",
      "is_fully_automated": true,
      "video_description": "Day in the life #plumbing",
      "tiktok_username": "plumber_pov",
      "scheduled_at": "2026-05-18"
    }]
  }'