---
title: "Import OTIO to timeline document"
method: POST
path: "/api/v1/timelines/import/otio"
tags: ["Timelines"]
---

# Import OTIO to timeline document

`POST /api/v1/timelines/import/otio`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/timelines/import/otio`
- Auth: HTTP bearer

Imports an `.otio` file or ZIP bundle into a Kaitoi Timeline Document v1. When media files are present in the ZIP, they are persisted to the authenticated account's library and the returned document references those library filenames. Missing media produces warnings instead of server path leaks.

## Headers

- `authorization` string, nullable

## Response `200`

Timeline document converted from OTIO, with persisted media info.

- PublicTimelineOtioImportResponse
  - `document` object, required: Timeline Document produced from the OTIO input.
  - `summary` PublicTimelineSummary, required
    - `trackCount` integer, required: Number of tracks in the timeline.
    - `clipCount` integer, required: Number of clips in the timeline.
    - `durationSeconds` number, required: Timeline project duration in seconds.
  - `warnings` PublicTimelineWarning[]: Non-fatal import warnings.
    - `code` string, required: Stable warning code.
    - `message` string, required: Human-readable warning message.
    - `path` string, nullable: Path or media reference associated with the warning.
  - `files` PublicTimelineOtioImportedFile[]: Media files persisted by the import route. Empty for parse-only imports.
    - `filename` string, required: Original media filename from the OTIO archive.
    - `storagePath` string, required: Library storage filename used by the returned timeline document.
    - `dataType` 'image' | 'video' | 'audio', required: Detected media type.

## Other responses

- `400`: The OTIO upload is invalid.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `413`: The upload exceeds the request size limit.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `501`: OpenTimelineIO is unavailable.
- `503`: The shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)