# Projects and versions

A project holds one composition: its `data.json` and the files it uses. This page shows how to create a project, edit it, undo a change, copy it and export a version.

## Create a project

The example creates a project, then adds `data.json` from the current folder as its first version. It reads `BLITFRAME` and `BLITFRAME_API_KEY` from the environment, set as in the [quickstart](/docs/blitframe/quickstart#get-an-api-key).

::: code-tabs
```bash
PROJECT_ID=$(curl -s -X POST $BLITFRAME/projects \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Summer ad"}' | jq -r .id)

jq -Rs '{files: [{path: "data.json", content: .}]}' data.json |
  curl -s -X POST $BLITFRAME/projects/$PROJECT_ID/versions \
    -H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
    -d @- | jq '{renderable, problems}'
```
```python
import os, requests

api = os.environ["BLITFRAME"]
headers = {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"}

project = requests.post(f"{api}/projects", headers=headers, json={"name": "Summer ad"}).json()
project_id = project["id"]

with open("data.json", encoding="utf-8") as file:
    files = [{"path": "data.json", "content": file.read()}]
version = requests.post(f"{api}/projects/{project_id}/versions", headers=headers, json={"files": files}).json()
print(version["renderable"], version["problems"])
```
```javascript
import { readFile } from "node:fs/promises";

const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`, "Content-Type": "application/json" };

const project = await (
  await fetch(`${api}/projects`, { method: "POST", headers, body: JSON.stringify({ name: "Summer ad" }) })
).json();
const projectId = project.id;

const files = [{ path: "data.json", content: await readFile("data.json", "utf8") }];
const response = await fetch(`${api}/projects/${projectId}/versions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ files }),
});
const version = await response.json();
console.log(version.renderable, version.problems);
```
```php
<?php
function call(string $method, string $path, array $body): array {
    $ch = curl_init(getenv("BLITFRAME") . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    return json_decode(curl_exec($ch), true);
}

$project = call("POST", "/projects", ["name" => "Summer ad"]);
$projectId = $project["id"];

$files = [["path" => "data.json", "content" => file_get_contents("data.json")]];
$version = call("POST", "/projects/$projectId/versions", ["files" => $files]);
var_dump($version["renderable"], $version["problems"]);
```
```ruby
require "net/http"
require "json"

def call(method, path, body)
  uri = URI(ENV["BLITFRAME"] + path)
  headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}", "Content-Type" => "application/json" }
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.send_request(method, uri.request_uri, body.to_json, headers)
  end
  JSON.parse(response.body)
end

project = call("POST", "/projects", { name: "Summer ad" })
project_id = project["id"]

files = [{ path: "data.json", content: File.read("data.json", encoding: "utf-8") }]
version = call("POST", "/projects/#{project_id}/versions", { files: files })
p version["renderable"], version["problems"]
```
```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func call(method, path string, body any) map[string]any {
	payload, err := json.Marshal(body)
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(method, os.Getenv("BLITFRAME")+path, bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var out map[string]any
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	return out
}

func main() {
	project := call("POST", "/projects", map[string]any{"name": "Summer ad"})
	projectID := project["id"].(string)

	data, err := os.ReadFile("data.json")
	if err != nil {
		panic(err)
	}
	files := []map[string]any{{"path": "data.json", "content": string(data)}}
	version := call("POST", "/projects/"+projectID+"/versions", map[string]any{"files": files})
	fmt.Println(version["renderable"], version["problems"])
}
```
```csharp
using System.Net.Http.Json;
using System.Text.Json.Nodes;

var api = Environment.GetEnvironmentVariable("BLITFRAME");
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));

async Task<JsonNode> call(HttpMethod method, string path, object body)
{
    var request = new HttpRequestMessage(method, api + path) { Content = JsonContent.Create(body) };
    var response = await http.SendAsync(request);
    return (await response.Content.ReadFromJsonAsync<JsonNode>())!;
}

var project = await call(HttpMethod.Post, "/projects", new { name = "Summer ad" });
var projectId = (string?)project["id"];

var files = new[] { new { path = "data.json", content = await File.ReadAllTextAsync("data.json") } };
var version = await call(HttpMethod.Post, $"/projects/{projectId}/versions", new { files });
var problems = version["problems"]!.AsArray().Select(p => (string?)p);
Console.WriteLine($"{version["renderable"]} [{string.Join("; ", problems)}]");
```
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

public class Example {
    static JsonNode call(String method, String path, String body) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + path))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .method(method, HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        return new ObjectMapper().readTree(response.body());
    }

    public static void main(String[] args) throws Exception {
        JsonNode project = call("POST", "/projects", """
            {"name": "Summer ad"}
            """);
        String projectId = project.get("id").asText();

        String content = new ObjectMapper().writeValueAsString(Files.readString(Path.of("data.json")));
        JsonNode version = call("POST", "/projects/" + projectId + "/versions", """
            {"files": [{"path": "data.json", "content": %s}]}
            """.formatted(content));
        System.out.println(version.get("renderable") + " " + version.get("problems"));
    }
}
```
:::

The second request prints whether the new version can render, and its `problems`. If they list missing images or fonts, add those files in another edit.

Each edit saves a new **version**, a snapshot of every file that never changes, and moves the project's **head** to it. [Concepts](/docs/blitframe/concepts) explains the model.

All requests go to `https://blitframe.codeartworks.com` with an `Authorization: Bearer <api key>` header, and bodies are JSON.

`POST /v1/projects` can also start a project from a ZIP or from another version:

| Body | Creates |
|---|---|
| `{ "name": "Summer ad" }` | An empty project. The name is 1 to 200 characters. |
| `{ "name": "…", "zipUploadId": "…" }` | A project whose version 1 is a ZIP [upload](/docs/blitframe/uploads#use-it). |
| `{ "name": "…", "fromVersionId": "…" }` | A copy of a version ([duplicating a project](#duplicating-a-project)). |

Send at most one of `zipUploadId` and `fromVersionId`. An `Idempotency-Key` header makes a retry safe ([retrying safely](/docs/blitframe/api#retrying-safely)).

## Editing a project

`POST /v1/projects/{projectId}/versions`

```json
{
  "expectedHeadVersionId": "b7e2…",
  "message": "Change headline to Spanish",
  "files": [
    { "path": "data.json", "content": "{ \"v\": \"5.12.2\", … }" },
    { "path": "images/logo.png", "contentBase64": "iVBORw0KGgo…" },
    { "path": "video/background.mp4", "uploadId": "1c9d…" },
    { "path": "fonts/Inter-Bold.ttf", "fromVersionId": "4f0a…" }
  ],
  "delete": ["images/old-logo.png"]
}
```

An edit makes a new version from the head plus your changes, and moves the head to it. Files you don't mention carry over from the head unchanged. The response is `201 Created` with the new version.

| Field | Description |
|---|---|
| `files` | Files to add or replace. Each has a `path` and one [source](#files). |
| `delete` | Paths to remove from the head's files. |
| `expectedHeadVersionId` | Optional. The head your change was made on. If the head has moved since, the edit is refused with `409 head_moved` ([edits and the head](#edits-and-the-head)). |
| `message` | Optional description, cut off at 500 characters. Defaults to `Update`, or with `replacements` to a list of what changed, such as `Edit Headline text`. |
| `name` | Optional version name, up to 200 characters, such as `Approved cut`. It is set when the version is created and never changes. [Download file names](/docs/blitframe/renders#download-file-names) use it. |
| `variation` | Optional. The [variation](/docs/blitframe/variations) to edit, such as `spanish`. Defaults to `main`. |
| `fontLicenseAccepted` | Must be `true` when `files` adds a font file, except one copied with `fromVersionId`. It confirms you are licensed to render with it ([fonts](/docs/blitframe/fonts#licensing)). |
| `restoreFromVersionId` | Optional. Start from this version's files instead of the head's ([undoing a change](#undoing-a-change)). |
| `replacements` | Optional. Change text, fonts, images or video by layer without sending `data.json` ([replacements](/docs/blitframe/editing#replacements)). |
| `soundtrack` | Optional. The audio renders play by default ([soundtrack](#soundtrack)). |
| `textFittingBaselineVersionId` | Optional, with `text_fitting.json` in the version. The earlier version, from the variation's history, that [text fitting](/docs/blitframe/text-fitting#baseline-version) measures `originalBounds` against. |

An edit that changes nothing makes no version. It answers `200 OK` with the current head ([when an edit makes no version](#when-an-edit-makes-no-version)).

Send an `Idempotency-Key` header to make a retry safe. The same edit with the same key answers with the version the first one made ([retrying safely](/docs/blitframe/api#retrying-safely)). An edit that names uploads is safe to send again even without a key ([edits that name uploads](#edits-that-name-uploads)).

### Files

Each item in `files` has a `path` and exactly one source:

| Source | Sends |
|---|---|
| `content` | UTF-8 text, such as `data.json`. |
| `contentBase64` | A binary file, inside the request. |
| `uploadId` | A `ready` [upload](/docs/blitframe/uploads#use-it) whose `fileName` has the same extension as `path`. |
| `fromVersionId` | A file copied from any version in your workspace, without uploading it. `fromPath` names it there and defaults to `path` ([copy files](/docs/blitframe/uploads#copy-files-from-another-version)). |

The whole request body can be up to 64 MB. Base64 makes files about a third larger, so `contentBase64` fits files up to about 45 MB. [Upload](/docs/blitframe/uploads) anything bigger.

### Edits and the head

An edit applies to the head as it is when the edit runs: the head of `main`, or of the [variation](/docs/blitframe/variations) the edit names. If another edit lands first:

| Your edit | What happens |
|---|---|
| Without `expectedHeadVersionId`, or with `null` | There is no check. Your edit is made again on the new head. After three tries in all, it is refused with `409 head_moved`: send it again. |
| With `expectedHeadVersionId` | The head must still be that version. If it isn't, the edit is refused with `409 head_moved` and nothing changes. Get the project (or the variation), apply your change on its new head, and send it again. |

Without `expectedHeadVersionId`, your change goes on the head even if someone edited the project after you read it. That suits a change that doesn't depend on what you read, such as adding a file. Send `expectedHeadVersionId` when it does:

- A whole `data.json`, or a `restoreFromVersionId`, replaces what the head has, including changes made since.
- [Replacements](/docs/blitframe/editing#replacements) name layers by their position in `data.json`, which a newer `data.json` can change.

Edits to one variation never move another's head, so they never cause each other's `head_moved`.

### Soundtrack

`"soundtrack": { "path": "audio/music.mp3", "offsetSeconds": 0 }` sets the audio a render of this version plays. The path must be an audio file in the version.

- The audio starts `offsetSeconds` into the video (0 to 3,600). The video is silent until then, and the file plays from its beginning.
- Audio stops where the video ends, so an offset at or past the video's length gives a silent video.
- Later versions keep the soundtrack while its file stays. To remove it, delete the audio file.
- A render's own `audio` overrides it for that render ([renders](/docs/blitframe/renders#create-a-render)).

### Paths and file types

Paths are relative, use forward slashes (`images/logo.png`) and are 1 to 512 characters. The composition is always `data.json` at the root. [File rules](#file-rules) lists the characters a path can't use.

| Kind | Extensions |
|---|---|
| Composition and data | `.json` |
| Images | `.png`, `.jpg`, `.jpeg`, `.jfif`, `.tga`, `.webp`, `.avif`, `.heic`, `.heif`, `.tif`, `.tiff`, `.bmp`, `.gif`, `.psd` |
| Video | `.mp4`, `.mov`, `.m4v`, `.webm`, `.mkv`, `.avi`, `.mpg`, `.mpeg`, `.wmv`, `.flv`, `.ts`, `.mts`, `.m2ts` |
| Audio | `.mp3`, `.wav`, `.m4a`, `.aac`, `.flac`, `.ogg`, `.oga`, `.opus` (any codec that decodes; renders convert it to AAC) |
| Fonts | `.ttf`, `.otf`, `.woff`, `.woff2` |
| 3D models | `.glb` and `.gltf`, self-contained |

Each file's contents are checked against its extension. A version holds up to 5,000 files. `GET /v1/files/capabilities` returns this list with each type's size and dimension limits ([file capabilities](/docs/blitframe/uploads#file-capabilities)). [How media files render](#how-media-files-render) covers animated images, PSD files and video with alpha.

## Undoing a change

Versions are never changed or deleted, so you undo by editing again. Set `restoreFromVersionId` to the version to go back to:

```json
{ "expectedHeadVersionId": "b7e2…", "restoreFromVersionId": "4f0a…", "message": "Back to the English headline" }
```

- The new version has exactly the files and soundtrack of `4f0a…`, and becomes the head. The versions in between stay in the [history](#versions).
- `restoreFromVersionId` can be any version of the project; any other id is `404 not_found`. That includes one from another [variation](/docs/blitframe/variations)'s history, and the version a [render with replacements](/docs/blitframe/editing#in-a-render) made, which keeps that render's changes in the project.
- `expectedHeadVersionId` is optional, as in any edit. With it, the restore is refused with `409 head_moved` if someone edited the project after you chose the version.
- Add `files`, `delete` or `replacements` to change something at the same time.

## Variations

A variation is a second head in a project, with its own history, such as the video in Spanish next to the original. Every project has one called `main`, which requests use when they name no variation. [Variations](/docs/blitframe/variations) shows how to create, edit, render and delete one.

## Duplicating a project

To copy a version into a project of its own, create a project with `fromVersionId`. Use it for a copy you will keep editing apart, such as one for a partner:

`POST /v1/projects`

```json
{ "name": "Summer ad (Spanish)", "fromVersionId": "b7e2…" }
```

The response is `201 Created` with the new project. The head of its `main` has that version's files, soundtrack, name and message.

- `fromVersionId` can be any version in your workspace, of any project, including the version a render made.
- A version larger than your plan's [project size](/docs/blitframe/limits#plan-limits) is copied only when a head of its project is at least as large. Otherwise, such as a render's own version that its replacements made larger, the copy is `403 project_too_large`.
- Only that version is copied. Its history, other variations, renders and share links are not.
- When the version's text fitting measures against another version ([baseline](/docs/blitframe/text-fitting#baseline-version)), that version is copied first. The new project then starts with two versions and fits text exactly as the original does.
- Nothing is uploaded again. A copy is quick whatever its size, and needs no `fontLicenseAccepted`.
- The copy is checked again in the new project, so its `renderable` and `problems` are current.
- Edits to the copy never change the original, and the reverse.

To find copies, [list projects](#list-rename-and-delete-projects) with `copiedFromVersionId` for the copies of one version. Use `copiedFromProjectId` for the copies of any version of a project, such as every language of a project. [Copy details](#copy-details) has the refusals and what happens when the original is deleted.

To make many one-off videos, or to keep an alternative in the same project, you don't need a copy ([variation, copy or replacements](/docs/blitframe/variations#variation-copy-or-replacements)).

## Versions

| Method | Path | Does |
|---|---|---|
| `GET` | `/v1/projects/{projectId}/versions?variation=&limit=50&before={versionId}` | The history of `main`, or of the [variation](/docs/blitframe/variations) named, newest first: the head, then each version's parent. `limit` is 1 to 1,000 (default 50). Pass `next` as `before` to page. |
| `GET` | `/v1/versions/{versionId}` | One version with its files, composition details, problems and warnings. |
| `GET` | `/v1/versions/{versionId}/files/{path}` | Redirects (`302`) to a short-lived download link for one file. |
| `POST` | `/v1/versions/{versionId}/export` | Queue a ZIP of the whole version ([exporting a version](#exporting-a-version)). |
| `GET` | `/v1/versions/{versionId}/export/{exportId}` | The export's status and, once ready, its download link. |

The history lists the versions the head was made from. A version that a [render with replacements](/docs/blitframe/editing#in-a-render) made is in no history, unless a variation starts at it. Get it by the render's `versionId`.

A version looks like this:

```json
{
  "id": "b7e2…",
  "projectId": "9a0f…",
  "parentVersionId": "4f0a…",
  "number": 5,
  "message": "Change headline to Spanish",
  "createdAt": "2026-11-05T20:00:00+00:00",
  "composition": { "width": 1920, "height": 1080, "frameRate": 30, "durationSeconds": 6, "frameCount": 180 },
  "renderable": true,
  "problems": [],
  "warnings": [],
  "soundtrack": null,
  "textFittingBaselineVersionId": null,
  "files": [{ "path": "data.json", "sizeBytes": 48211, "contentType": "application/json", "sha256": "…" }],
  "name": "Approved cut"
}
```

| Field | Meaning |
|---|---|
| `parentVersionId` | The version this one was made from, or `null` for a project's first version. A render's version has the version the render pinned. |
| `number` | Counts up across the project. Versions made by renders and by edits to other variations take numbers too, so a history can skip one. |
| `composition` | Read from `data.json`, or `null` when it cannot be read. |
| `renderable` | `true` when `problems` is empty. |
| `files` | The version's files. It is `null` on each item of the history list: get the version for its files. |
| `soundtrack` | The default render audio, or `null` ([soundtrack](#soundtrack)). |
| `textFittingBaselineVersionId` | The version [text fitting](/docs/blitframe/text-fitting#baseline-version) measures original text against, or `null`. |

### Problems and warnings

`problems` lists everything that stops the version from rendering. Fix them in another edit. For example:

- a missing `data.json`, or invalid JSON,
- an asset or font that is not in the version,
- a shape or text layer with nothing to draw,
- composition values outside Blitframe's limits, such as a frame rate above 120.

At most 50 problems are listed. A last entry says when there are more.

`warnings` list things that render, but differently than you might expect:

- An odd width or height. MP4 and HLS video need even dimensions.
- A [text fitting](/docs/blitframe/text-fitting#checking-and-rendering) rule that could not be applied, or text that cannot fit at its `minSize`.
- Characters a font has no glyphs for. They render as the font's missing-glyph symbol, usually an empty box. The warning names the layer, the font and the characters.
- A text layer Blitframe could not check for missing glyphs or overflowing text. Its font cannot be measured, or would take the version's fonts past 128 MB.

To change text, fonts, images or video without rewriting `data.json`, see [Editing layers](/docs/blitframe/editing).

### Project files

`GET /v1/projects/{projectId}/files?kind=image&q=logo&limit=100&after=…` lists every distinct file across the project's versions, sorted by path:

```json
{
  "items": [
    { "path": "images/logo.png", "kind": "image", "sizeBytes": 48211, "contentType": "image/png", "sha256": "9f86…", "versionId": "b7e2…", "versionNumber": 5 }
  ],
  "next": "NTppbWFnZXMv…"
}
```

A path whose content changed between versions appears once per content. `versionId` is the latest version holding that exact file. Use it to download the file, or to copy it into an edit with `fromVersionId`.

| Parameter | Description |
|---|---|
| `kind` | Optional: `composition` (the root `data.json`), `json`, `image`, `video`, `audio`, `font` or `model`. |
| `q` | Optional: part of the path, any case, up to 200 characters. |
| `limit` | 1 to 1,000, default 100. |
| `after` | The `next` value of the previous page. |

## Exporting a version

`POST /v1/versions/{versionId}/export` (no body) queues one ZIP of every file in the version. The ZIP has the layout you would upload, so you can import it into another project, or into this one. The response is `202 Accepted` with the export.

Get it with `GET /v1/versions/{versionId}/export/{exportId}`. Send [`Prefer: wait=N`](/docs/blitframe/renders#waiting-for-a-result) to hold the answer until it is `ready` or `failed`:

```json
{
  "id": "…",
  "versionId": "b7e2…",
  "status": "ready",
  "fileName": "Summer-ad-v5.zip",
  "url": "https://…",
  "sizeBytes": 18211933,
  "error": null,
  "createdAt": "2026-11-05T20:00:00+00:00",
  "finishedAt": "2026-11-05T20:00:04+00:00",
  "expiresAt": "2026-11-06T20:00:00+00:00"
}
```

| `status` | Meaning |
|---|---|
| `queued` | Waiting to be built. |
| `building` | Being built. |
| `ready` | `url` downloads the ZIP. The link lasts up to an hour. Get the export again for a fresh one. |
| `failed` | `error` (`code` and `message`) says why. `interrupted` means the build stopped on Blitframe's side. Request a new export. |

With a [webhook](/docs/blitframe/webhooks), `version_export.ready` or `version_export.failed` tells you when it is done.

A renderable version's [text fitting](/docs/blitframe/text-fitting) is applied to the exported `data.json`, and `text_fitting.json` is left out. Importing the export keeps the fitted text but not the rules.

[Limits](/docs/blitframe/limits#renders) has the export's size, lifetime and queue limits. [Export details](#export-details) has the rest.

## List, rename and delete projects

| Method | Path | Does |
|---|---|---|
| `GET` | `/v1/projects?q=&copiedFromVersionId=&copiedFromProjectId=&limit=100&before=` | List projects, newest first. |
| `POST` | `/v1/projects` | Create a project ([create a project](#create-a-project)). |
| `GET` | `/v1/projects/{projectId}` | Get one project. |
| `PATCH` | `/v1/projects/{projectId}` | Rename it: `{ "name": "…" }`. |
| `DELETE` | `/v1/projects/{projectId}` | Delete the project with its variations, versions, renders and share links. Cancel its queued and running renders first, or you get `409 renders_active`. |
| `GET` | `/v1/projects/{projectId}/files` | List every file across its versions ([project files](#project-files)). |
| `POST` | `/v1/projects/{projectId}/package` | Import a ZIP upload as the next version of `main`, or of the `variation` it names: `{ "zipUploadId": "…" }` ([uploads](/docs/blitframe/uploads#use-it)). Takes an `Idempotency-Key` header. |
| `GET` | `/v1/projects/{projectId}/package/{importId}` | Status of an import that answered `202` ([large ZIPs](/docs/blitframe/uploads#large-zips)). |

The list takes these parameters:

| Parameter | Description |
|---|---|
| `q` | Part of the project name, up to 200 characters. |
| `copiedFromVersionId`, `copiedFromProjectId` | Only the [copies](#duplicating-a-project) of that version, or of any version of that project. |
| `limit` | 1 to 1,000, default 100. |
| `before` | The `next` value of the previous page, for older projects. Lists end when `next` is `null`. |

A project looks like this:

```json
{
  "id": "9a0f…",
  "name": "Summer ad",
  "createdAt": "2026-11-05T19:00:00+00:00",
  "headVersionId": "b7e2…",
  "renderable": true,
  "copiedFromVersionId": null,
  "thumbnailUrl": "https://…"
}
```

| Field | Meaning |
|---|---|
| `headVersionId` | The head of the project's `main` [variation](/docs/blitframe/variations). Edits and renders of the project use it when they name no other variation. `null` while the project is empty. |
| `renderable` | Whether that head can render, or `null` while the project is empty. The head's `problems` say why not. |
| `copiedFromVersionId` | For a [copy](#duplicating-a-project), the version it was made from. It is kept even after that version's project is deleted. `null` for any other project. |
| `thumbnailUrl` | The [poster](/docs/blitframe/renders#posters) of the project's latest succeeded MP4 or HLS render, or `null` before there is one. The link lasts an hour. |

## Details

### When an edit makes no version

An edit makes no version when the files, soundtrack and text fitting baseline end up exactly as the head has them. That happens with no files, with the same content again, or when you restore the head itself. A new version is still made when:

- the edit names an upload (making a version is what uses the upload up),
- the head has `problems` (the files are checked again, so anything that has become available since is picked up),
- the edit gives a `name` different from the head's, or
- the project is empty (its first edit always makes a version, even with no files).

### Edits that name uploads

An edit that names uploads can be sent again exactly as it was after it used them. It answers `200 OK` with the version it made and the header `Idempotent-Replayed: true`, even without an `Idempotency-Key`. So retrying after a lost answer is safe. A different edit that names an upload already used is `400 invalid_request`.

### File rules

- Paths cannot start with `/`. They cannot contain `\`, `.` or `..` segments, control characters or any of `" : * ? < > |`, so an exported ZIP unzips on any system. For the same reason no folder or file name may end in a dot or a space, or be a name Windows reserves (`CON`, `PRN`, `AUX`, `NUL`, `COM0` to `COM9`, `LPT0` to `LPT9`), with or without an extension, such as `con.png` (`400`).
- A version's files can total at most your plan's [project size](/docs/blitframe/limits#plan-limits). An edit that makes a version larger is `403 project_too_large`. One that keeps a version already past it the same size or smaller is accepted.
- Two paths in a version cannot differ only in letter case, such as `images/Logo.png` and `images/logo.png`, or only in how an accented letter is encoded, as `é` can be one character or `e` plus an accent (`400`).
- A file copied with `fromVersionId` keeps its file type. The root `data.json` copies only to and from another version's root `data.json`.

### How media files render

| File | How it renders |
|---|---|
| Animated GIF and WebP | Plays once as video, then holds its last frame. |
| PSD | Renders its merged composite. |
| TIFF and AVIF | Must hold a single image. |
| Video with alpha | Keeps its alpha. ProRes 4444, QuickTime Animation or PNG in MOV or MP4, upright and at most 4096 pixels on each side, is used as it is. Other video with alpha is converted to PNG in MOV. Export alpha video premultiplied (matted) against black. |
| Other video that needs converting | Becomes H.264, or PNG in MOV when its width or height is odd. Rotated video is turned upright. Full-range or BT.2020 video is re-encoded with the BT.709 matrix in limited range, without converting BT.2020 colors ([format reference](/docs/blitframe/data-json-format#media-and-precompositions)). |

### Copy details

- A `fromVersionId` that doesn't exist or belongs to another workspace is `404 not_found`. `fromVersionId` together with `zipUploadId` is `400 invalid_request`.
- A version larger than your plan's [project size](/docs/blitframe/limits#plan-limits) can still be copied.
- If the original project is deleted later, the copy keeps its `copiedFromVersionId`, but the id no longer leads to a version.
- `copiedFromProjectId` finds copies only while that project exists. `copiedFromVersionId` finds them after it is deleted too.

### Export details

- A version over 8 GB in total is refused with `400`. Download its files one by one.
- A workspace can have 10 exports waiting or building. Another gets `409 export_limit`. Each workspace builds one export at a time.
- Asking again for a version whose export is queued, building, or ready with more than an hour before it expires returns that same export.
- Exports are kept for 24 hours.
