API Overview
Overview of VideoCascade API structure and conventions
Base URL
https://api.videocascade.comAPI Version
The current API version is v1. All endpoints are prefixed with /v1:
https://api.videocascade.com/v1/videosRequest Format
All API requests must include:
- Authentication:
Authorization: Bearer vca_your_api_keyheader - Content-Type:
application/jsonfor JSON requests - Request Body: JSON-encoded parameters for POST/PATCH requests
Example Request
POST /v1/videos HTTP/1.1
Host: api.videocascade.com
Authorization: Bearer vca_your_api_key
Content-Type: application/json
{
"fileUrl": "https://example.com/video.mp4",
"removeSilence": true,
"outputFormat": "mp4"
}Response Format
All responses are JSON-encoded with appropriate HTTP status codes.
Success Response
{
"videoId": "v_abc12345",
"jobId": "j_xyz98765",
"status": "queued"
}Error Response
{
"error": "ValidationError",
"message": "Invalid parameter: fileUrl must be a valid URL",
"details": {
"field": "fileUrl",
"reason": "Invalid URL format"
}
}HTTP Status Codes
VideoCascade API uses conventional HTTP response codes:
| Status Code | Meaning |
|---|---|
200 | OK - Request succeeded |
201 | Created - Resource created successfully |
202 | Accepted - Request accepted for processing |
400 | Bad Request - Invalid parameters or request format |
401 | Unauthorized - Missing or invalid API key |
403 | Forbidden - Valid API key but insufficient permissions |
404 | Not Found - Resource doesn't exist |
409 | Conflict - Resource conflict (e.g., duplicate) |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error - Server error |
503 | Service Unavailable - Service temporarily unavailable |
Error Handling
Error Response Structure
{
"error": "ErrorType",
"message": "Human-readable error message",
"details": {
"additionalInfo": "value"
}
}Common Error Types
| Error Type | Description | HTTP Status |
|---|---|---|
ValidationError | Invalid request parameters | 400 |
AuthenticationError | Invalid or missing API key | 401 |
NotFoundError | Resource not found | 404 |
RateLimitError | Too many requests | 429 |
ProcessingError | Video processing failed | 500 |
StorageError | Storage operation failed | 500 |
Example Error Handling
try {
const response = await fetch('https://api.videocascade.com/v1/videos', {
method: 'POST',
headers: {
Authorization: 'Bearer vca_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({ fileUrl: 'invalid-url' }),
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message);
}
const data = await response.json();
} catch (error) {
console.error('API error:', error.message);
}Timestamps
All timestamps are returned in ISO 8601 format (UTC):
{
"createdAt": "2024-11-23T10:30:00Z",
"updatedAt": "2024-11-23T10:45:00Z"
}Endpoint Categories
Video Processing
- POST /v1/videos - Create video processing job from URL
- POST /v1/videos/upload - Upload and process video file
- GET /v1/videos/{videoId} - Get video status and details
- GET /v1/videos/{videoId}/transcript - Get video transcript
System
- GET /health - Health check (no auth required)
Rate Limits
API requests are rate-limited based on your plan. When you exceed the limit:
{
"error": "RateLimitError",
"message": "Rate limit exceeded. Please try again later.",
"retryAfter": 60
}The retryAfter field indicates how many seconds to wait before retrying.
Rate Limit Headers
Responses include rate limit information in headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700720460Webhooks
Get notified when video processing completes by providing a webhookUrl:
{
"fileUrl": "https://example.com/video.mp4",
"webhookUrl": "https://yourapp.com/webhooks/video-complete"
}