Bevyl
HomeBrandsAgenciesUse casesPricingTrendsFAQ
Sign inBook a demo
☰
HomeBrandsAgenciesUse casesPricingTrendsFAQ

Developers

Bevyl API Reference

Generated reference for Bevyl public API surfaces: endpoints, request and response schemas, and auth, including partner workspace integrations.

OpenAPI JSON

MCP

Authenticated Model Context Protocol transport.

POST/api/mcp

Handle MCP streamable HTTP requests

Accepts JSON-RPC requests from authenticated Model Context Protocol clients over streamable HTTP.

Auth
bearerAuth

Public API v1

User-scoped REST API for OAuth-connected tools and workflow connectors.

POST/api/v1/projects

Create a project (generate a video)

Starts an asynchronous video generation for the connected workspace. Poll /api/v1/generations/{generationId} until completed.

Auth
bearerAuth
GET/api/v1/projects

List or search projects

Auth
bearerAuth
GET/api/v1/projects/{projectId}

Read a project

Auth
bearerAuth
GET/api/v1/generations/{generationId}

Poll a project generation

Auth
bearerAuth
GET/api/v1/videos

List source videos

Source videos in the connected workspace, newest first — footage available for createProject.

Auth
bearerAuth
POST/api/v1/videos/import

Import a source video from a URL

Auth
bearerAuth
GET/api/v1/imports/{importId}

Poll a video import

Auth
bearerAuth
POST/api/v1/exports

Start an MP4 export

Auth
bearerAuth
GET/api/v1/exports

List recent completed exports

Sample-data feed for connector trigger tests. Payload shape matches the export.completed webhook; the export id is the dedupe key.

Auth
bearerAuth
GET/api/v1/exports/{exportId}

Poll an export / get its download URL

Auth
bearerAuth
POST/api/v1/webhooks

Subscribe to a webhook event

REST-hook subscribe endpoint for connector instant triggers. v1 supports export.completed only. The signing secret is returned only in this create response.

Auth
bearerAuth
GET/api/v1/webhooks

List active webhook subscriptions

Auth
bearerAuth
DELETE/api/v1/webhooks

Unsubscribe a webhook

Auth
bearerAuth

Mobile API v1

First-party mobile API authenticated with a Supabase user access token.

GET/api/mobile/v1/activity

List resumable workspace activity

Returns workspace generations and exports plus uploads started by the signed-in user.

Auth
supabaseBearerAuth
POST/api/mobile/v1/push-subscriptions

Register the signed-in user push endpoint

Auth
supabaseBearerAuth
DELETE/api/mobile/v1/push-subscriptions/{installationId}

Disable push endpoints for this signed-in app installation

Auth
supabaseBearerAuth
GET/api/mobile/v1/workspaces

List workspaces visible to the signed-in user

Auth
supabaseBearerAuth
GET/api/mobile/v1/videos

List source videos in the selected workspace

Auth
supabaseBearerAuth
GET/api/mobile/v1/videos/{videoId}

Read a source video in the selected workspace

Auth
supabaseBearerAuth
GET/api/mobile/v1/uploads/{uploadId}

Read upload, processing, and resulting video status

Auth
supabaseBearerAuth
POST/api/mobile/v1/uploads/admission

Check whether a source video upload may start

Auth
supabaseBearerAuth
GET/api/mobile/v1/projects

List projects in the selected workspace

Auth
supabaseBearerAuth
POST/api/mobile/v1/projects

Create a project and start generation

Auth
supabaseBearerAuth
GET/api/mobile/v1/project-create-options

Read project creation options for the selected workspace

Auth
supabaseBearerAuth
GET/api/mobile/v1/projects/{projectId}

Read a project in the selected workspace

Auth
supabaseBearerAuth
PATCH/api/mobile/v1/projects/{projectId}

Update a project in the selected workspace

Auth
supabaseBearerAuth
GET/api/mobile/v1/projects/{projectId}/timeline

Read the canonical project timeline for the native editor

Auth
supabaseBearerAuth
POST/api/mobile/v1/projects/{projectId}/timeline

Apply a pending-changes batch to the native editor timeline

Auth
supabaseBearerAuth
GET/api/mobile/v1/generations/{generationId}

Read project generation status

Auth
supabaseBearerAuth
POST/api/mobile/v1/exports

Start an MP4 export for a project

Auth
supabaseBearerAuth
GET/api/mobile/v1/exports/{exportId}

Read MP4 export status and signed media URLs

Auth
supabaseBearerAuth

Health

Service health checks.

GET/api/health

Check web API health

Auth
none

Partner API v1

Partner-scoped JSON API. Inbound requests use bearer API keys stored as SHA-256 hashes in `integration_partner_api_keys`; each request names a `workspaceId` authorized through `integration_partner_workspaces`. Outbound partner webhooks are signed separately with HMAC-SHA256 secrets from `integration_partner_secrets`.

POST/api/partner/v1/workspaces

Provision a partner workspace

Creates the customer account mapped to `workspaceId`. Repeating the request for an active workspace owned by the same partner is idempotent.

Auth
partnerApiKey
Request
PartnerWorkspaceCreateInput
StatusSchema
200PartnerWorkspaceCreateResponse
401PartnerHttpError
403PartnerHttpError
409PartnerHttpError
500PartnerHttpError
GET/api/partner/v1/brand

Get partner workspace brand context

Returns the active brand context for the workspace mapped from `workspaceId`.

Auth
partnerApiKey
StatusSchema
200PartnerBrandGetResponse
401PartnerHttpError
403PartnerHttpError
404PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/brand

Update partner workspace brand fields

Updates the active brand profile for the workspace mapped from `workspaceId`.

Auth
partnerApiKey
Request
PartnerBrandInput
StatusSchema
200PartnerBrandResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
GET/api/partner/v1/projects

List projects and generation history

Returns projects in the mapped workspace with the creative brief and status for each generation attempt.

Auth
partnerApiKey
StatusSchema
200PartnerProjectListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/projects

Create a Bevyl project

Creates a project from uploaded source videos and queues generation.

Auth
partnerApiKey
Request
PartnerProjectCreateInput
StatusSchema
202PartnerProjectCreateResponse
401PartnerHttpError
402PartnerProjectCreateResponse
403PartnerHttpError
422PartnerProjectCreateResponse
500PartnerHttpError
POST/api/partner/v1/projects/regenerate

Regenerate an existing project

Queues a new generation for an existing project. Omitted brief fields carry over from the most recent generation; provided fields override it.

Auth
partnerApiKey
Request
PartnerProjectRegenerateInput
StatusSchema
202PartnerProjectCreateResponse
401PartnerHttpError
402PartnerProjectCreateResponse
403PartnerHttpError
404PartnerProjectCreateResponse
409PartnerProjectCreateResponse
422PartnerProjectCreateResponse
500PartnerHttpError
POST/api/partner/v1/projects/status

Get project generation status

Returns the latest generation run for a project, or a specific run when `runId` is provided.

Auth
partnerApiKey
Request
PartnerProjectStatusInput
StatusSchema
200PartnerProjectStatusResponse
401PartnerHttpError
403PartnerHttpError
404PartnerProjectStatusResponse
500PartnerHttpError
GET/api/partner/v1/background-music

List background music choices

Returns a compact Epidemic Sound catalog for checkout. Pass a returned track ID as `backgroundMusicTrackId` when creating a project.

Auth
partnerApiKey
StatusSchema
200PartnerBackgroundMusicListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/background-music/preview

Preview a background music choice

Returns a temporary MP3 URL for auditioning an Epidemic Sound track before project creation.

Auth
partnerApiKey
Request
PartnerBackgroundMusicPreviewInput
StatusSchema
200PartnerBackgroundMusicPreviewResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
GET/api/partner/v1/trends

List published trending sounds

Returns the published trend catalog. Pass a returned trend ID to project creation with `format: "trending-sounds"`.

Auth
partnerApiKey
StatusSchema
200PartnerTrendListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
GET/api/partner/v1/voices

List available voice profiles

Returns active public voices and custom voices available to the mapped workspace.

Auth
partnerApiKey
StatusSchema
200PartnerVoiceListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/videos/upload/prepare

Prepare a direct video upload

Creates a partner-staged upload session and returns a signed PUT URL.

Auth
partnerApiKey
Request
PartnerVideoUploadPrepareInput
StatusSchema
200PartnerVideoUploadPrepareResponse
401PartnerHttpError
402PartnerOperationErrorResponse
403PartnerHttpError
422PartnerHttpError
500PartnerHttpError
GET/api/partner/v1/videos

List uploaded source videos

Returns source videos uploaded through the mapped partner workspace, newest first.

Auth
partnerApiKey
StatusSchema
200PartnerVideoListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/videos/upload/complete

Complete a direct video upload

Finalizes an uploaded object and starts video processing for the mapped workspace.

Auth
partnerApiKey
Request
PartnerVideoUploadCompleteInput
StatusSchema
200PartnerVideoUploadCompleteResponse
202PartnerVideoUploadCompleteResponse
401PartnerHttpError
402PartnerHttpError
403PartnerHttpError
404PartnerHttpError
409PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/videos/status

Get video processing status

Returns processing state for a video in the mapped workspace.

Auth
partnerApiKey
Request
PartnerVideoStatusInput
StatusSchema
200PartnerVideoStatusResponse
401PartnerHttpError
403PartnerHttpError
404PartnerVideoStatusResponse
500PartnerHttpError
GET/api/partner/v1/exports

List project exports

Returns partner-attributed MP4 exports in the mapped workspace with project identity and lifecycle status.

Auth
partnerApiKey
StatusSchema
200PartnerExportListResponse
401PartnerHttpError
403PartnerHttpError
500PartnerHttpError
POST/api/partner/v1/exports

Start a project export

Queues an MP4 export for a project in the mapped workspace.

Auth
partnerApiKey
Request
PartnerProjectExportInput
StatusSchema
202PartnerProjectExportResponse
401PartnerHttpError
402PartnerProjectExportResponse
403PartnerHttpError
404PartnerHttpError
422PartnerHttpError
500PartnerHttpError
502PartnerProjectExportResponse
POST/api/partner/v1/exports/status

Get export status

Returns export readiness and download URLs for an export in the mapped workspace.

Auth
partnerApiKey
Request
PartnerExportStatusInput
StatusSchema
200PartnerExportStatusResponse
401PartnerHttpError
403PartnerHttpError
404PartnerExportStatusResponse
500PartnerHttpError
bevyl.

Your personalized taste powered AI video-editing strategist.

© 2026 Bevyl Inc. All rights reserved.

Product
  • Why Bevyl
  • How It Works
  • For Brands
  • For Agencies
  • Solutions
  • Product video maker
  • AI video ad maker
  • UGC ad maker
  • Long video to shorts
  • Pricing
  • Tools
Company
  • About
  • Contact
  • Collaborate
Resources
  • TikTok Trends
  • Blog
  • Glossary
  • FAQ
  • Privacy & Data
  • Terms
Bevyl
HomeBrandsAgenciesUse casesPricingTrendsFAQ
Sign inBook a demo
    • Create Your First Project