ION Video API — Partner Integration Guide

1. Overview

ION virtualization turns an uploaded source video into a lightweight virtual MP4. The player receives metadata (ftyp + moov) immediately and fetches media data on demand. Partners use this to:

• Upload a source video and receive a UUID
• Virtualize that video through a fixed GraphQL pipeline
• Optionally compose multiple virtualized sources into a timed clip sequence

What you get back

file.id

Source video UUID used in every subsequent step

Virtual DREF MP4

Metadata-only MP4; media streams at playback time

assetId

Timed asset ID for the virtualized or composite result

mediaServerUrl

URL the player uses to fetch media data

2. Getting started

Prerequisites

• HTTPS client that can send multipart/form-data and JSON
• Ability to store the source video UUID between pipeline steps
• A JWT from ION for all GraphQL calls

Quick connectivity check

export BASE_URL="https://<api-base-url>"
export JWT="<provided-jwt>"

curl -s "$BASE_URL/health-check"
curl -s "$BASE_URL/uploads/health-check"
curl -s -X POST "$BASE_URL/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d '{"query":"query { health }"}'

Expected: REST health returns JSON with app_name / service; GraphQL returns { "data": { "health": "ok" } }.

3. Concepts

Source video UUID

Returned as file.id from upload. Pass this as uuid to reencodeMp4, sliceFmp4, and createDrefMp4, and as video_id inside composite clips.

Virtualization pipeline

Each source video must complete these steps in order:

Upload → reencodeMp4 → sliceFmp4 → createDrefMp4

DREF / virtual MP4

createDrefMp4 builds a referenced MP4 (ftyp + moov only). Media (mdat) is fetched later via mediaServerUrl. Persist assetId and mediaServerUrl from a successful response.

Composite (timed) clips

createTimedMp4 stitches one or more already virtualized source videos into a single timed composite. It is independent of the four-step pipeline, but every video_id in the clip list must have completed virtualization first.

4. Authentication

REST (/health-check, /uploads/...)

No authentication.

GraphQL (POST /graphql)

Auth failures return plain JSON (not a GraphQL envelope):

5. Required workflow — single video

5.1 Health checks

REST examples:

{ "app_name": "ion discovery proto" }
{ "service": "uploads" }

5.2 Upload video

POST /uploads/upload-video 201

Accepted MIME types:

video/mp4, video/quicktime, video/x-matroska, video/webm, video/x-msvideo, video/x-ms-wmv, video/mpeg

Success (abbreviated):

{
  "message": "Video uploaded successfully",
  "file": {
    "id": "018f3a2b-7c4e-7a1d-8f2b-1a2b3c4d5e6f",
    "original_name": "clip.mp4",
    "mime_type": "video/mp4",
    "size": 1234567,
    "duration": 10.5
  }
}

curl -s -X POST "$BASE_URL/uploads/upload-video" \
  -F "file=@./clip.mp4"

5.3 GraphQL virtualization

All operations: POST /graphql with Bearer JWT. Common argument: uuid (String!) — source video UUID from upload.

mutation ReencodeMp4($uuid: String!) {
  reencodeMp4(uuid: $uuid) {
    success
    uuid
    message
    error
  }
}

mutation SliceFmp4($uuid: String!) {
  sliceFmp4(uuid: $uuid) {
    success
    uuid
    initPath
    fragmentsPath
    error
  }
}

query CreateDrefMp4($uuid: String!) {
  createDrefMp4(uuid: $uuid) {
    success
    message
    uuid
    outputPath
    mediaServerUrl
    mdatLocation
    fileSize
    instructions
    assetId
    warnings
  }
}

6. Optional — composite timed clips

After one or more source videos are fully virtualized, stitch them with createTimedMp4.

mutation CreateTimedMp4($clips: [VideoClipInput!]!) {
  createTimedMp4(clips: $clips) {
    success
    message
    uuid
    outputPath
    mediaServerUrl
    mdatLocation
    fileSize
    instructions
    assetId
    warnings
  }
}

Clip input

Clips play in array order. The same video_id may appear more than once with different ranges.

Example variables:

{
  "clips": [
    { "video_id": "018f3a2b-7c4e-7a1d-8f2b-1a2b3c4d5e6f" },
    {
      "video_id": "0190abcd-1234-5678-9abc-def012345678",
      "startTime": 10,
      "endTime": 60
    },
    {
      "video_id": "018f3a2b-7c4e-7a1d-8f2b-1a2b3c4d5e6f",
      "startTime": 5,
      "endTime": 10
    }
  ]
}

Notes for integrators

• Every video_id must exist and should already be virtualized
• startTime may be adjusted to a prior keyframe for reliable decode; check warnings
• On thrown errors, expect top-level GraphQL errors (e.g. missing source videos)
• On operation-level failure, inspect data.createTimedMp4.success where applicable

7. Error handling

Always treat GraphQL HTTP 200 as transport success only. Inspect success and errors in the body before continuing the pipeline.

Recommended client logic

1. If HTTP status is 401/403 → refresh or request a new JWT
2. If REST status is not 2xx → abort; surface error
3. If GraphQL body has errors → abort; surface errors[].message
4. If data.<op>.success === false → abort; surface error; do not advance to the next step

8. End-to-end example

BASE_URL="https://<api-base-url>"
JWT="<provided-jwt>"

# 0. Health
curl -s "$BASE_URL/health-check"
curl -s "$BASE_URL/uploads/health-check"

# 1. Upload
UPLOAD=$(curl -s -X POST "$BASE_URL/uploads/upload-video" -F "file=@./clip.mp4")
UUID=$(echo "$UPLOAD" | jq -r '.file.id')
echo "UUID=$UUID"

# 2. Re-encode
curl -s -X POST "$BASE_URL/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d "{\"query\":\"mutation(\$u:String!){reencodeMp4(uuid:\$u){success error}}\",\"variables\":{\"u\":\"$UUID\"}}"

# 3. Slice
curl -s -X POST "$BASE_URL/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d "{\"query\":\"mutation(\$u:String!){sliceFmp4(uuid:\$u){success error initPath fragmentsPath}}\",\"variables\":{\"u\":\"$UUID\"}}"

# 4. Create DREF virtual MP4 (query)
curl -s -X POST "$BASE_URL/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT" \
  -d "{\"query\":\"query(\$u:String!){createDrefMp4(uuid:\$u){success assetId mediaServerUrl warnings}}\",\"variables\":{\"u\":\"$UUID\"}}"

# 5. Optional — composite (requires additional virtualized UUIDs)
# curl -s -X POST "$BASE_URL/graphql" \
#   -H "Content-Type: application/json" \
#   -H "Authorization: Bearer $JWT" \
#   -d '{"query":"mutation($clips:[VideoClipInput!]!){createTimedMp4(clips:$clips){success uuid assetId mediaServerUrl warnings}}","variables":{"clips":[{"video_id":"'"$UUID"'"}]}}'

9. Integration checklist

Checks persist in this browser via localStorage.

• Received JWT and confirmed base URL with ION
• Health checks succeed (REST + GraphQL)
• Upload returns 201 and a stable file.id
• Pipeline runs in order: reencode → slice → createDref
• Client treats GraphQL HTTP 200 as transport-only and checks success / errors
• assetId and mediaServerUrl are stored for playback
• (If composites) each clip video_id is virtualized before createTimedMp4
• Client schemas and examples aligned with this guide (and any contract ION provides privately)

10. Support

Credentials and base URL are issued privately by the ION team for your environment.

Appendix — GraphQL response types

type ReencodeMp4Response {
  success: Boolean!
  uuid: String!
  message: String
  error: String
  meta: JSON
}

type SliceFmp4Response {
  success: Boolean!
  uuid: String!
  initPath: String
  fragmentsPath: String
  error: String
}

type CreateDrefMp4Response {
  success: Boolean!
  message: String!
  uuid: String!
  outputPath: String!
  mediaServerUrl: String!
  mdatLocation: String!
  fileSize: String!
  instructions: String!
  assetId: String!
  warnings: [String!]
}

input VideoClipInput {
  video_id: String!
  startTime: Float
  endTime: Float
}

createTimedMp4 returns the same shape as CreateDrefMp4Response (including assetId and warnings).