API Reference

The VDClip public API lets your servers create projects, render clips, manage brand assets, and publish to social platforms. It is a REST API at https://api.vdclip.com under /v1/*, authenticated with an API key in the Authorization header.


curl https://api.vdclip.com/v1/account \
  -H 'Authorization: Bearer vdck_your_key_here'

The API is server-to-server only. It has no CORS and rejects browser requests. Keep your vdck_... key on your backend and treat it like a password.

Successful /v1 responses return resource data directly:


{
  "id": "acc_...",
  "plan": "pro"
}

On failure, responses return errors[] with code and description. Include X-Request-ID when you contact contact@vdclip.com.

OAuth 2.1 for user-delegated clients

VDClip also runs an OAuth 2.1 Authorization Server at /oauth2/* and /.well-known/* for MCP servers, AI agents, and third-party integrations acting on behalf of a user. Those endpoints use standard RFC bodies, not the /v1 envelope. See OAuth 2.1.

Explore the API

🔑

Authentication

API keys, the Authorization Bearer header, and scopes

AuthenticationHow API keys, the Authorization Bearer header, and scopes work

🌐

REST API basics

Base URL, responses, pagination, errors

ConventionsBase URL, the direct JSON response, cursor pagination, and error codes

👤

Account

Profile, plan, and credit balance

AccountRead the account profile, plan, and credit balance

📁

Projects

Create clipping and captions projects

ProjectsCreate, list, inspect, share, and delete projects and their clips

🎬

Clips

Inspect, render, and publish clips

ClipsGet clip detail, react, render, and publish or schedule clips

🧩

Templates

Reusable layout and caption presets

TemplatesCreate, read, update, and delete reusable templates

🎨

Assets

Brand-kit asset uploads

AssetsList and read brand-kit assets

📅

Calendar

Scheduled and posted content

CalendarList, reschedule, and cancel scheduled posts

📣

Social

Connected social accounts

SocialList the social accounts connected to the workspace

🤖

MCP Servers

Model Context Protocol for AI assistants

MCP ServersTools and resources for AI assistants acting on a user behalf

🔐

OAuth 2.1

Authorization server for user-delegated clients

OAuth 2.1Discovery, registration, authorize, token, and revoke endpoints

Two ways to authenticate

API key. The primary surface. Send Authorization: Bearer vdck_... on every /v1 request from your own backend. Each key holds scopes that decide what it can do. See Authentication.
OAuth 2.1. For MCP servers, AI agents, and third-party integrations acting on behalf of a user. These clients send Authorization: Bearer <JWT>. See OAuth 2.1 and MCP Servers.

Scopes

Scopes take the form vdclip:<resource>:<action>, for example vdclip:projects:read. A request without the scope it needs returns MISSING_SCOPE. Two scopes are plan-gated: vdclip:render:execute and vdclip:social:publish.

The full catalog is in MCP Servers. To unlock a gated capability, upgrade on the pricing page →.

Errors and rate limits

When something fails, error.code tells you what to do:

Code	Meaning
`INVALID_API_KEY`	The key is missing, malformed, or revoked.
`MISSING_SCOPE`	The key is valid but lacks the scope this endpoint needs.
`INSUFFICIENT_CREDITS`	The account is out of credits for the action.
`RATE_LIMITED`	Too many requests. Returned with HTTP 429 and a `Retry-After` header.
`UPSTREAM_ERROR`	A downstream service failed. Safe to retry.
`VALIDATION_ERROR`	The request body or query parameters failed validation.
`INVALID_JSON`	The request body was not valid JSON.
`NOT_FOUND`	The resource does not exist or is not visible to this key.
`ORIGIN_REJECTED`	The request came from a browser origin. The API is server-to-server only.

On RATE_LIMITED, wait the seconds in Retry-After before retrying. List endpoints use cursor pagination: pass cursor and limit, then follow the returned cursor. Defaults and maximums are in the REST API conventions.

Tips & Best Practices

Keep keys server-side

Never ship vdck_ keys to browsers, mobile apps, or any client. The API has no CORS and rejects browser origins with ORIGIN_REJECTED.

Request only the scopes you need

Grant each key the minimum set of vdclip:<resource>:<action> scopes to limit blast radius if it leaks.

Honor Retry-After

On HTTP 429, back off for the seconds in the Retry-After header instead of retrying immediately.

Log the request_id

Store X-Request-ID from each response so support can trace any issue you report to contact@vdclip.com.

Use OAuth for user-delegated clients

Use the OAuth 2.1 server when an MCP server, AI agent, or integration acts on behalf of a user. Server-to-server jobs should use an API key.