HesedVid API Reference

The HesedVid API provides a comprehensive REST interface for video management, delivery, and analytics. Built for developers who need reliable, scalable video infrastructure, our API offers everything from upload and transcoding to playback and analytics.

Why HesedVid API?

• Developer-First Design: Clean, intuitive REST endpoints with comprehensive documentation
• Enterprise-Grade Reliability: 99.9% uptime SLA with global CDN delivery
• Flexible Authentication: API keys with environment-specific and full-access options
• Advanced Video Processing: Automatic transcoding with multiple quality levels
• Real-Time Analytics: Detailed usage metrics and performance insights

Quick Start

Get up and running with the HesedVid API in minutes:

cURL Example

# Upload a video (API key created in HesedVid dashboard)
curl -X POST "https://api.hesedvid.com/v1/api/org_123456789/environments/env_prod_123456789/videos/upload-url" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-video.mp4",
    "fileSize": 10485760,
    "contentType": "video/mp4"
  }'

JavaScript Example

// Upload a video (API key created in HesedVid dashboard)
const uploadVideo = async () => {
  const response = await fetch('https://api.hesedvid.com/v1/api/org_123456789/environments/env_prod_123456789/videos/upload-url', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      filename: 'my-video.mp4',
      fileSize: 10485760,
      contentType: 'video/mp4'
    })
  });
  return response.json();
};

Base URL

All API requests should be made to:

https://api.hesedvid.com/v1/api

Authentication

The HesedVid API supports two authentication methods:

API Key Authentication (Recommended for Applications)

For programmatic access, use API key authentication by including your API key in the X-Api-Key header:

X-Api-Key: hv_live_123456789abcdefghijklmnopqrstuvwxyz

Example with cURL:

curl -X GET \
  -H "X-Api-Key: hv_live_123456789abcdefghijklmnopqrstuvwxyz" \
  "https://api.hesedvid.com/v1/api/{orgID}/videos"

Example with JavaScript:

const response = await fetch('https://api.hesedvid.com/v1/api/{orgID}/videos', {
  headers: {
    'X-Api-Key': 'hv_live_123456789abcdefghijklmnopqrstuvwxyz',
    'Content-Type': 'application/json'
  }
});

API Key Types

• Environment-Specific Keys: Limited to a single environment (recommended for production)
• Full-Access Keys: Can access all environments (use for administrative tasks)

Core Features

Video Management

• Video Upload - Request signed URLs for direct video upload to cloud storage
• Video Playback - Stream videos with HLS and generate signed URLs for private content
• Video Management - List, retrieve details, and delete videos with comprehensive metadata

Advanced Features

• Thumbnail Generation: Create custom thumbnails at any timestamp
• Share Links: Generate shareable links with expiration and view limits

Response Format

All API responses follow a consistent format:

Success Response

{
  "body": {
    "videoID": "vid_123456789abcdef",
    "publicID": "pubvid_AbCdEf",
    "status": "ready",
    "duration": "00:02:30",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid video quality specified",
  "errors": [
    {
      "message": "expected value to be one of \"standard\", \"high\", \"ultra\" but got \"invalid\"",
      "location": "body.videoOptions.videoQuality",
      "value": "invalid"
    }
  ]
}

Error Handling

The API uses standard HTTP status codes and provides detailed error information:

Error Response Example

{
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data",
  "errors": [
    {
      "message": "Video quality must be one of: standard, high, ultra",
      "location": "body.videoOptions.videoQuality",
      "value": "invalid_quality"
    },
    {
      "message": "File size must be between 1MB and 10GB",
      "location": "body.fileSize",
      "value": 15000000000
    }
  ]
}

Rate Limiting

API requests are rate limited to ensure fair usage and system stability:

Rate limit information is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1640995200

SDKs and Libraries

While the HesedVid API is designed to work with any HTTP client, we recommend using our official SDKs for the best developer experience:

• JavaScript/TypeScript: @hesedvid/sdk (Coming Soon)
• Python: hesedvid-python (Coming Soon)
• Go: github.com/hesedvid/go-sdk (Coming Soon)

Getting Help

• Documentation: Comprehensive guides and API reference
• Support: Email [email protected] for technical assistance
• Health Endpoint: Check GET /health for service status

What’s Next?

Ready to start building? Here are the recommended next steps:

1. Set up Authentication: Create your first API key in the HesedVid dashboard and understand the authentication flow
2. Upload Your First Video: Learn how to upload and process videos
3. Implement Playback: Add video streaming to your application
4. Explore Analytics: Monitor usage and performance metrics

Start with the Video Upload guide to upload your first video, or explore the Authentication overview to understand how to secure your API calls.