API Overview

The Kensa REST API allows you to programmatically generate videos, manage credits, and receive real-time notifications through webhooks.

Base URL

https://your-domain.com/api/v1

All API endpoints are prefixed with /api/v1.

Authentication

All API requests require authentication via session cookies. When calling from a browser, include credentials:

const response = await fetch('/api/v1/video/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ /* ... */ })
});

The API uses Better Auth for session management. Users must be logged in with an active session to access API endpoints.

Authentication Errors

Status Code	Meaning
401	Not authenticated -- no valid session found
403	Forbidden -- insufficient permissions (e.g., non-admin accessing admin endpoints)

Request Format

• All request bodies must be JSON with Content-Type: application/json.
• Query parameters are used for GET requests.
• All responses return JSON.

Response Format

Success Response

{
  "success": true,
  "data": { /* response data */ }
}

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Available Endpoints

Endpoint	Method	Description
/api/v1/video/generate	POST	Start video generation
/api/v1/video/list	GET	List user's videos
/api/v1/video/[uuid]	GET	Get video details
/api/v1/video/[uuid]	DELETE	Delete a video
/api/v1/video/task	GET	Get generation task status
/api/v1/credit/history	GET	Get credit transaction history
/api/v1/config/models	GET	Get available AI models
/api/v1/video/callback/[provider]	POST	AI provider webhook callback

Rate Limiting

API requests are subject to rate limiting to ensure fair usage. If you exceed the rate limit, you will receive a 429 Too Many Requests response. Wait and retry after the period indicated in the response headers.

Pagination

List endpoints support pagination via query parameters:

GET /api/v1/video/list?page=1&pageSize=20

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
pageSize	number	20	Items per page