Create a Project

POST /v1/projects

Create a project folder to organize videos in your workspace. Each project belongs to the workspace tied to the API key used.

Request body

Parameter	Type	Required	Description
name	string	Yes	Display name (1–200 chars)
description	string	No	Optional description (up to 1000 chars)
thumbnailUrl	string	No	Project thumbnail URL
access	object	No	Who can open the project — see Project Access. Defaults to the whole workspace.

Example

curl -X POST https://api.vidocu.ai/v1/projects \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch",
    "description": "All onboarding and demo videos for the Q1 launch"
  }'

Response 201 Created

{
  "id": "0f7c1d8a-2c4b-4a9c-9f2a-1b8a3a5e0c11",
  "name": "Q1 Product Launch",
  "description": "All onboarding and demo videos for the Q1 launch",
  "thumbnailUrl": null,
  "access": { "mode": "workspace", "memberIds": [] },
  "createdAt": "2026-04-27T10:00:00.000Z",
  "updatedAt": "2026-04-27T10:00:00.000Z"
}

Required scope

OAuth tokens need the projects:write scope. API keys are unscoped.

Errors

Status	Code	Cause
400	validation_error	name missing or invalid field length
401	authentication_error	Invalid or missing API key
403	insufficient_scope	OAuth token missing projects:write
403	insufficient_role	access supplied by a role that can't manage members

Next step

Pass the returned id as projectId when uploading a video or running /process to organize videos into this folder.