REST API

The VDClip public API is a server-to-server REST interface under https://api.vdclip.com/v1. You authenticate with Authorization: Bearer <token>, where the token is either a VDClip API key (vdck_...) or an OAuth access token. Each credential is scoped to the resources you grant it.

Base URL and versioning

• Base URL: https://api.vdclip.com
• REST surface: every endpoint is prefixed with /v1, for example https://api.vdclip.com/v1/projects.
• OAuth surface: the OAuth 2.1 server lives under /oauth2/* and /.well-known/*. Those endpoints follow the relevant RFCs. See Authentication.

Authentication

Send your API key in the Authorization header as a Bearer token on every /v1 request.

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

API keys carry a fixed set of scopes and draw from your credit balance. For clients acting on behalf of a user, use OAuth 2.1 with a Bearer token instead; see OAuth 2.1.

Responses

Successful /v1 endpoints return the resource directly as JSON. Errors return an errors array. Include X-Request-ID and X-Trace-ID response headers when you contact contact@vdclip.com.

{
  "errors": [
    {
      "code": "INSUFFICIENT_CREDITS",
      "description": "Your account does not have enough credits for this operation."
    }
  ]
}

Error codes

Pagination

List endpoints use cursor pagination: limit sets the page size, and cursor is an opaque token from the previous page (do not parse or build it yourself). Defaults and maximums vary per endpoint and are defined in the OpenAPI spec.

# First page
curl 'https://api.vdclip.com/v1/projects?limit=20' \
  -H 'Authorization: Bearer vdck_your_key_here'
 
# Next page, using the cursor from the previous response
curl 'https://api.vdclip.com/v1/projects?limit=20&cursor=eyJpZCI6IjEyMyJ9' \
  -H 'Authorization: Bearer vdck_your_key_here'

Idempotency

POST /v1/projects supports the Idempotency-Key header (max 200 chars). Send the same key on retry and the API replays the original response without creating a duplicate project. Use a unique value per operation; UUIDs work well.

curl -X POST https://api.vdclip.com/v1/projects \
  -H "Authorization: Bearer vdck_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Scopes

Scopes follow the pattern vdclip:<resource>:<action>. There are 15. A request without the scope an endpoint requires fails with MISSING_SCOPE. Two scopes are plan-gated: vdclip:render:execute and vdclip:social:publish require a plan that includes them. See the pricing page .

Endpoint reference

All /v1 endpoints, grouped by resource. Full schemas and request bodies are generated from the OpenAPI spec.

Account

Projects

Clips

Templates

Assets

Calendar

Social

OAuth 2.1 for user-delegated clients

For MCP servers, AI agents, and integrations acting on behalf of a user, VDClip runs an OAuth 2.1 Authorization Server (issuer https://api.vdclip.com). These clients send Authorization: Bearer <JWT> instead of an API key.

Related pages

Tips & Best Practices

Frequently Asked Questions