API

Written By Lukas Klinzing

Last updated About 1 year ago

VideoToPage Client API Documentation

The VideoToPage Client API allows you to validate API tokens, manage video processing workflows, and handle media uploads. This guide covers authentication, endpoints, request/response formats, and example usage.

Table of Contents

Overview

The API supports operations to:

  • Validate API Tokens: Confirm the validity of your JWT and retrieve user details.

  • Manage Workflows: List workflows, check workflow executions, and start new executions from a URL.

  • Manage Media Uploads: Retrieve lists of uploads and detailed information about specific uploads.

All endpoints require authentication via a Bearer (JWT) token.

Base URL

All API endpoints are prefixed with the following base path:

/video2doc/europe-west3/clientApi

For example, the full URL to validate your API token is:

https://your-api-domain.com/video2doc/europe-west3/clientApi/api/validate

Note: Replace https://your-api-domain.com with the actual domain for your deployment.

Authentication

Every request to the API must include a valid JSON Web Token (JWT) in the Authorization header using the Bearer scheme.

Header Example:

Authorization: Bearer <your_jwt_token_here>

Ensure you obtain a valid token before making API calls.

Endpoints

1. Validate API Token

Endpoint: POST /api/validate

Purpose:
Validates the provided API token and returns the authenticated user's details along with token metadata.

Request:

  • Headers:

    • Authorization: Bearer <token>

  • Body:
    No body is required.

Response (200 OK):

{
  "user": {
    "id": "user123",
    "displayName": "John Doe",
    "email": "john.doe@example.com"
  },
  "token": {
    "valid": true,
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

Error Response (401 Unauthorized):
Returned if the token is invalid or expired.

2. List All Workflows

Endpoint: GET /api/workflows

Purpose:
Retrieves a list of workflows available to the authenticated user.

Request:

  • Headers:

    • Authorization: Bearer <token>

Response (200 OK):

{
  "workflows": [
    {
      "id": "workflow1",
      "name": "Video Processing",
      "description": "Workflow for processing video files",
      "createdAt": "2025-01-01T12:00:00Z",
      "updatedAt": "2025-01-10T15:30:00Z",
      "steps": [
        {
          "id": "step1",
          "type": "transcoding",
          "config": { "resolution": "1080p" }
        }
      ]
    }
  ]
}

Error Response (401 Unauthorized):
Returned if authentication fails.

3. List Workflow Executions

Endpoint: GET /api/workflows/{workflowId}/executions

Purpose:
Lists all executions for a specific workflow.

Path Parameter:

  • workflowId (string, required): Unique identifier for the workflow.

Request:

  • Headers:

    • Authorization: Bearer <token>

Response (200 OK):

{
  "executions": [
    {
      "id": "exec123",
      "status": "running",
      "createdAt": "2025-02-01T08:00:00Z",
      "updatedAt": "2025-02-01T08:15:00Z"
    }
  ]
}

Error Responses:

  • 401 Unauthorized: If authentication fails.

  • 404 Not Found: If the specified workflow does not exist.

4. Get Workflow Execution Details

Endpoint: GET /api/workflows/{workflowId}/executions/{executionId}

Purpose:
Retrieves detailed information about a specific workflow execution, including the status of individual workflow steps.

Path Parameters:

  • workflowId (string, required): Unique identifier for the workflow.

  • executionId (string, required): Unique identifier for the execution.

Request:

  • Headers:

    • Authorization: Bearer <token>

Response (200 OK):

{
  "id": "exec123",
  "status": "IN_PROGRESS",
  "createdAt": "2025-02-01T08:00:00Z",
  "updatedAt": "2025-02-01T08:15:00Z",
  "steps": [
    {
      "id": "step1",
      "type": "download",
      "status": "COMPLETED",
      "url": "https://example.com/resource",
      "error": null
    }
  ]
}

Error Responses:

  • 401 Unauthorized: If authentication fails.

  • 404 Not Found: If the execution is not found.

5. Create a New Workflow Execution from a URL

Endpoint: POST /api/workflows/{workflowId}/execution/new/url

Purpose:
Starts a new workflow execution by providing a URL (e.g., a YouTube video). Optionally, you can specify a webhook URL to be notified when the workflow completes.

Path Parameter:

  • workflowId (string, required): Unique identifier for the workflow.

Request:

  • Headers:

    • Authorization: Bearer <token>

    • Content-Type: application/json

  • Body:
    JSON object with the following properties:

    • Required:

      • url (string, format: URL)
        Example: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

    • Optional:

      • webhookUrl (string, format: URL): Callback URL to be notified upon completion.

Example Request Body:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "webhookUrl": "https://yourapp.com/webhook"
}

Response (201 Created):

{
  "executionId": "exec124",
  "status": "NOT_STARTED"
}

Error Responses:

  • 401 Unauthorized: If the token is invalid.

  • 404 Not Found: If the specified workflow is not found.

6. List Media Uploads

Endpoint: GET /api/uploads

Purpose:
Retrieves a list of media uploads for the authenticated user.

Request:

  • Headers:

    • Authorization: Bearer <token>

Response (200 OK):

{
  "uploads": [
    {
      "id": "media123",
      "title": "My Vacation Video",
      "description": "A video from my summer vacation",
      "status": "processed",
      "metadata": {
        "durationInSeconds": 120,
        "hasAudio": true,
        "hasVideo": true
      },
      "source": {
        "type": "upload",
        "data": {}
      },
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-02-01T10:05:00Z"
    }
  ]
}

Error Response (401 Unauthorized):
Returned if authentication fails.

7. Get Media Upload Details

Endpoint: GET /api/uploads/{mediaId}

Purpose:
Retrieves detailed information about a specific media upload, including processing features and any errors.

Path Parameter:

  • mediaId (string, required): Unique identifier for the media upload.

Request:

  • Headers:

    • Authorization: Bearer <token>

Response (200 OK):

{
  "id": "media123",
  "title": "My Vacation Video",
  "description": "A video from my summer vacation",
  "status": "processed",
  "metadata": {
    "durationInSeconds": 120,
    "hasAudio": true,
    "hasVideo": true
  },
  "source": {
    "type": "upload",
    "data": {}
  },
  "features": [
    {
      "id": "feat1",
      "type": "thumbnail",
      "generationState": "COMPLETED",
      "error": null
    }
  ],
  "createdAt": "2025-02-01T10:00:00Z",
  "updatedAt": "2025-02-01T10:05:00Z"
}

Error Responses:

  • 401 Unauthorized: If authentication fails.

  • 404 Not Found: If the media upload is not found.

Example Usage

Validate an API Token Using cURL

curl -X POST "https://your-api-domain.com/video2doc/europe-west3/clientApi/api/validate" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create a New Workflow Execution from a URL

curl -X POST "https://your-api-domain.com/video2doc/europe-west3/clientApi/api/workflows/workflow1/execution/new/url" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -d '{
           "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
           "webhookUrl": "https://yourapp.com/webhook"
         }'

Final Notes

  • Error Handling:
    Standard HTTP status codes are returned (e.g., 401 Unauthorized for invalid credentials, 404 Not Found for missing resources). Ensure your application gracefully handles these errors.

  • Date-Time Format:
    Timestamps are provided in ISO 8601 format (e.g., "2025-02-01T10:00:00Z").

  • Updates:
    The API schema may evolve over time. Check for updates to the documentation for any changes.

This documentation should help you effectively integrate and work with the VideoToPage Client API. For further questions or advanced usage, please consult the API support or additional developer resources provided by your service.