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

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,
  "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

Next step

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