API Documentation

Automate your video captioning workflow with the CanvaSub REST API. Available on Pro and Team plans.

Authentication

All API requests require an API key passed in the X-API-Key header. Generate API keys from your workspace settings under API Keys.

curl -H "X-API-Key: cs_your_api_key_here" \
  https://canvasub.com/api/v1/health

Keep your API keys secret. Do not expose them in client-side code or public repositories.

Base URL

https://canvasub.com/api/v1

Rate Limiting

API requests are limited to 60 requests per minute per API key. Rate limit headers are included in every response:

X-RateLimit-Remaining — Requests remaining in the current window
X-RateLimit-Reset — Seconds until the rate limit resets

Endpoints

GET/api/v1/health

Check API and database connectivity.

Response

{
  "status": "healthy",
  "timestamp": "2025-01-31T12:00:00.000Z",
  "version": "1.0.0",
  "services": { "database": "connected" }
}

GET/api/v1/projects

List all projects in your workspace.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`sortBy`	string	Sort field: updatedAt, createdAt, name
`sortOrder`	string	asc or desc (default: desc)

Example

curl -H "X-API-Key: cs_your_key" \
  "https://canvasub.com/api/v1/projects?page=1&limit=10"

Response

{
  "success": true,
  "data": [
    {
      "id": "proj_abc123",
      "name": "My Video",
      "status": "READY",
      "aspectRatio": "PORTRAIT_9_16",
      "sourceAsset": { "id": "...", "name": "video.mp4", "duration": 120 },
      "transcript": { "id": "...", "language": "en" },
      "renderJobs": [{ "id": "...", "status": "COMPLETED", "outputUrl": "..." }]
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 42, "totalPages": 5 }
}

POST/api/v1/projects

Create a new project.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Project name
`aspectRatio`	string	No	PORTRAIT_9_16, SQUARE_1_1, or LANDSCAPE_16_9
`speechLanguage`	string	No	ISO language code (default: auto)

Example

curl -X POST -H "X-API-Key: cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Video", "aspectRatio": "PORTRAIT_9_16"}' \
  "https://canvasub.com/api/v1/projects"

Error Handling

All errors return a JSON response with an error field:

{
  "error": "Invalid API key",
  "status": 401
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad request / validation error
401	Unauthorized / invalid API key
403	Forbidden / insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Need Help?

If you have questions about the API, check our contact page or email us at hello@canvasub.com.