API Overview

Base URLs, endpoints, response formats, error handling, content types, and pagination for the Clipzy ML Engine API.

Base URL

All endpoints are relative to the following base URL:

http://{host}/api/v1

Replace {host} with the hostname or IP address of your Clipzy ML Engine instance.

Endpoints

Method	Path	Description
GET	/api/v1/health	Check service health
POST	/api/v1/videos/upload	Upload a video file
POST	/api/v1/jobs	Create a new processing job
GET	/api/v1/jobs/{job_id}	Get job status
GET	/api/v1/jobs/{job_id}/result	Get job result when completed
GET	/api/v1/jobs	List jobs with pagination

Content types

Endpoint	Request content type
POST /api/v1/videos/upload	multipart/form-data
All other endpoints	application/json

All responses are returned as application/json.

Standard response envelope

Every successful response wraps its payload in a standard envelope:

{
  "success": true,
  "message": "Human-readable message",
  "data": { ... }
}

success · boolean · required

true for all successful responses.

message · string · required

A human-readable description of the outcome.

data · object · required

The response payload. Shape varies by endpoint — see individual endpoint pages for details.

Error response format

When a request fails, the API returns a non-2xx HTTP status code and the following body:

{
  "success": false,
  "message": "Descriptive error message",
  "error": {
    "detail": "Technical details",
    "code": "ERROR_CODE"
  }
}

success · boolean · required

Always false for error responses.

message · string · required

A human-readable description of what went wrong.

error · object · required

Show properties

detail · string · required

Technical detail about the error, suitable for debugging.

code · string · required

Machine-readable error code string (e.g., VIDEO_NOT_FOUND, INVALID_FORMAT).

Pagination

List endpoints accept pagination query parameters and include pagination metadata in the response.

Query parameters

page · integer · default: "1"

The page number to retrieve, starting at 1.

page_size · integer · default: "10"

The number of items to return per page.

Paginated response

Paginated responses include the following fields alongside the result array:

total · integer

Total number of items across all pages.

page · integer

The current page number.

page_size · integer

The number of items returned per page.