Developers

Bevyl API Reference

Generated reference for Bevyl public API surfaces, 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.

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/uploads/{uploadId}

Read upload, processing, and resulting video status

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

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

Status	Schema
200	PartnerWorkspaceCreateResponse
401	PartnerHttpError
403	PartnerHttpError
409	PartnerHttpError
500	PartnerHttpError

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

Status	Schema
200	PartnerBrandResponse
401	PartnerHttpError
403	PartnerHttpError
500	PartnerHttpError

POST/api/partner/v1/projects

Create a Bevyl project

Creates a project from uploaded source videos and queues generation.

Auth: partnerApiKey
Request: PartnerProjectCreateInput

Status	Schema
202	PartnerProjectCreateResponse
401	PartnerHttpError
402	PartnerProjectCreateResponse
403	PartnerHttpError
422	PartnerProjectCreateResponse
500	PartnerHttpError

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

Status	Schema
200	PartnerProjectStatusResponse
401	PartnerHttpError
403	PartnerHttpError
404	PartnerProjectStatusResponse
500	PartnerHttpError

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

Status	Schema
200	PartnerVideoUploadPrepareResponse
401	PartnerHttpError
402	PartnerOperationErrorResponse
403	PartnerHttpError
422	PartnerHttpError
500	PartnerHttpError

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

Status	Schema
200	PartnerVideoUploadCompleteResponse
202	PartnerVideoUploadCompleteResponse
401	PartnerHttpError
402	PartnerHttpError
403	PartnerHttpError
404	PartnerHttpError
409	PartnerHttpError
500	PartnerHttpError

POST/api/partner/v1/videos/status

Get video processing status

Returns processing state for a video in the mapped workspace.

Auth: partnerApiKey
Request: PartnerVideoStatusInput

Status	Schema
200	PartnerVideoStatusResponse
401	PartnerHttpError
403	PartnerHttpError
404	PartnerVideoStatusResponse
500	PartnerHttpError

POST/api/partner/v1/exports

Start a project export

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

Auth: partnerApiKey
Request: PartnerProjectExportInput

Status	Schema
202	PartnerProjectExportResponse
401	PartnerHttpError
402	PartnerProjectExportResponse
403	PartnerHttpError
404	PartnerHttpError
422	PartnerHttpError
500	PartnerHttpError
502	PartnerProjectExportResponse

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

Status	Schema
200	PartnerExportStatusResponse
401	PartnerHttpError
403	PartnerHttpError
404	PartnerExportStatusResponse
500	PartnerHttpError