API reference / Projects

Edit a project

POST/v1/projects/{projectId}/versions

Adds, replaces or deletes files, or replaces layers, on top of the head of a variation (variation, or main when it is left out), as a new version that becomes that variation's head. With expectedHeadVersionId, the head must still be that version (409 head_moved otherwise); without it, the change applies to whatever the head is, and is made again on a newer head when another change lands first (409 head_moved after three tries). Each file has content, contentBase64, uploadId or fromVersionId (copies that version's file at fromPath, which defaults to path, from any version of the workspace; the file type must stay the same, and the root data.json copies only to and from another root data.json). An uploadId must name a ready upload whose fileName has the path's extension: one not completed is 409 upload_incomplete, one still being checked 409 upload_processing (naming every such upload, with Retry-After), and a failed one 409 upload_failed (giving the upload's own error). name optionally labels the version (at most 200 characters). restoreFromVersionId starts from any version of the project instead of the head, which undoes later changes. A request that adds a font file needs fontLicenseAccepted true (400 font_license_required otherwise). An edit that leaves the files, soundtrack and text fitting baseline as the head has them creates no version: the answer is 200 with the head. It still creates one when the head has problems (the files are checked again), when it gives a name other than the head's, or when it names an upload. An edit sent again after it used its uploads answers 200 with the version it made, with Idempotent-Replayed: true, when the body is the same. A version whose files would total more than the plan's project size (limits.maxProjectBytes in the usage) is refused with 403 project_too_large; one already larger may stay that size or shrink. Send an Idempotency-Key header (1 to 200 characters) to make retries safe: for 24 hours the same request with the same key answers with what the first one made, with the header Idempotent-Replayed: true; the same key with a different request is 422 idempotency_key_reused while what the first one made exists, and while the first request is still running 409 idempotency_key_in_use, except that the retry of a ZIP import waits for that import, as the first request does. A request that failed made nothing, so it can be sent again with its key.

Request

curl -s -X POST $BLITFRAME/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d36583c-7cfe-784c-08d2-148fa0e34888" \
  -d '{
    "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
    "message": "Change the headline",
    "files": [
      {
        "path": "data.json",
        "content": "{\"v\":\"5.12.2\",\"nm\":\"Summer sale\",\"fr\":30,\"ip\":0,\"op\":150,\"w\":1920,\"h\":1080,\"assets\":[],\"layers\":[]}"
      },
      {
        "path": "images/logo.png",
        "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      }
    ],
    "delete": ["images/old-logo.png"]
  }'
import os, requests

response = requests.post(
    f"{os.environ['BLITFRAME']}/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions",
    headers={
        "Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}",
        "Idempotency-Key": "7d36583c-7cfe-784c-08d2-148fa0e34888",
    },
    json={
        "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
        "message": "Change the headline",
        "files": [
            {
                "path": "data.json",
                "content": "{\"v\":\"5.12.2\",\"nm\":\"Summer sale\",\"fr\":30,\"ip\":0,\"op\":150,\"w\":1920,\"h\":1080,\"assets\":[],\"layers\":[]}",
            },
            {
                "path": "images/logo.png",
                "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
            },
        ],
        "delete": ["images/old-logo.png"],
    },
)
print(response.json())
const response = await fetch(`${process.env.BLITFRAME}/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "7d36583c-7cfe-784c-08d2-148fa0e34888",
  },
  body: JSON.stringify({
    expectedHeadVersionId: "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
    message: "Change the headline",
    files: [
      {
        path: "data.json",
        content: "{\"v\":\"5.12.2\",\"nm\":\"Summer sale\",\"fr\":30,\"ip\":0,\"op\":150,\"w\":1920,\"h\":1080,\"assets\":[],\"layers\":[]}",
      },
      {
        path: "images/logo.png",
        contentBase64: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      },
    ],
    delete: ["images/old-logo.png"],
  }),
});
console.log(await response.json());
<?php
$request = curl_init(getenv("BLITFRAME") . "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions");
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: 7d36583c-7cfe-784c-08d2-148fa0e34888",
    ],
    CURLOPT_POSTFIELDS => '{
      "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
      "message": "Change the headline",
      "files": [
        {
          "path": "data.json",
          "content": "{\\"v\\":\\"5.12.2\\",\\"nm\\":\\"Summer sale\\",\\"fr\\":30,\\"ip\\":0,\\"op\\":150,\\"w\\":1920,\\"h\\":1080,\\"assets\\":[],\\"layers\\":[]}"
        },
        {
          "path": "images/logo.png",
          "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
        }
      ],
      "delete": ["images/old-logo.png"]
    }',
]);
$response = curl_exec($request);
echo $response;
require "net/http"

uri = URI(ENV["BLITFRAME"] + '/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions')
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer " + ENV["BLITFRAME_API_KEY"]
request["Content-Type"] = "application/json"
request['Idempotency-Key'] = '7d36583c-7cfe-784c-08d2-148fa0e34888'
request.body = '{
  "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
  "message": "Change the headline",
  "files": [
    {
      "path": "data.json",
      "content": "{\\"v\\":\\"5.12.2\\",\\"nm\\":\\"Summer sale\\",\\"fr\\":30,\\"ip\\":0,\\"op\\":150,\\"w\\":1920,\\"h\\":1080,\\"assets\\":[],\\"layers\\":[]}"
    },
    {
      "path": "images/logo.png",
      "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    }
  ],
  "delete": ["images/old-logo.png"]
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
	  "message": "Change the headline",
	  "files": [
	    {
	      "path": "data.json",
	      "content": "{\"v\":\"5.12.2\",\"nm\":\"Summer sale\",\"fr\":30,\"ip\":0,\"op\":150,\"w\":1920,\"h\":1080,\"assets\":[],\"layers\":[]}"
	    },
	    {
	      "path": "images/logo.png",
	      "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
	    }
	  ],
	  "delete": ["images/old-logo.png"]
	}`)
	request, err := http.NewRequest("POST", os.Getenv("BLITFRAME")+"/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions", body)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	request.Header.Set("Content-Type", "application/json")
	request.Header.Set("Idempotency-Key", "7d36583c-7cfe-784c-08d2-148fa0e34888")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	text, _ := io.ReadAll(response.Body)
	fmt.Println(string(text))
}
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post,
    Environment.GetEnvironmentVariable("BLITFRAME") + "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
request.Headers.Add("Idempotency-Key", "7d36583c-7cfe-784c-08d2-148fa0e34888");
request.Content = new StringContent(
    """
    {
      "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
      "message": "Change the headline",
      "files": [
        {
          "path": "data.json",
          "content": "{\"v\":\"5.12.2\",\"nm\":\"Summer sale\",\"fr\":30,\"ip\":0,\"op\":150,\"w\":1920,\"h\":1080,\"assets\":[],\"layers\":[]}"
        },
        {
          "path": "images/logo.png",
          "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
        }
      ],
      "delete": ["images/old-logo.png"]
    }
    """, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        var request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/versions"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "7d36583c-7cfe-784c-08d2-148fa0e34888")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "expectedHeadVersionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
                  "message": "Change the headline",
                  "files": [
                    {
                      "path": "data.json",
                      "content": "{\\"v\\":\\"5.12.2\\",\\"nm\\":\\"Summer sale\\",\\"fr\\":30,\\"ip\\":0,\\"op\\":150,\\"w\\":1920,\\"h\\":1080,\\"assets\\":[],\\"layers\\":[]}"
                    },
                    {
                      "path": "images/logo.png",
                      "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
                    }
                  ],
                  "delete": ["images/old-logo.png"]
                }
                """))
            .build();
        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Path parameters

  • projectIdstring (uuid)required

Headers

  • AuthorizationBearer Blitframe API keyrequired

    API key from the developer console.

  • Idempotency-Keystring

    Optional. A unique key you choose for this one request, 1 to 200 characters, such as a new UUID. Send the same key again only to retry this request after a lost answer: the retry answers with what the first one made instead of doing it again. Use a new key for every other request; the key in the samples is only an example.

Body

application/json · required · EditProjectRequest

  • expectedHeadVersionIdstring (uuid) or null
  • messagestring or null
  • filesarray of EditFile or null
    EditFile fields
    • pathstringrequired
    • contentstring or null
    • contentBase64string or null
    • uploadIdstring (uuid) or null
    • fromVersionIdstring (uuid) or null
    • fromPathstring or null
  • deletearray of string or null
  • restoreFromVersionIdstring (uuid) or null
  • namestring or null
  • fontLicenseAcceptedboolean

    Default false

  • soundtrackAudioTrack or null
    AudioTrack fields
    • pathstringrequired
    • offsetSecondsnumber

      Default 0

  • textFittingBaselineVersionIdstring (uuid) or null
  • replacementsarray of Replacement or null
    Replacement fields
    • layerstringrequired
    • textstring or null
    • fontstring or null
    • pathstring or null
    • fileEditFile or null
      EditFile fields
      • pathstringrequired
      • contentstring or null
      • contentBase64string or null
      • uploadIdstring (uuid) or null
      • fromVersionIdstring (uuid) or null
      • fromPathstring or null
    • fitMediaFit or null

      One of contain cover

  • variationstring or null

Try it

POST/v1/projects/{projectId}/versions

Used for the requests you send from this page only. It is not saved.

This sends a real request to your workspace: a render spends render seconds, and a delete is final.

Response

Send the request to see the answer here.

Responses

  • 200 OK
  • 201 Created

application/json · VersionDto

  • idstring (uuid)
  • projectIdstring (uuid)
  • parentVersionIdstring (uuid) or null
  • numberinteger
  • messagestring
  • createdAtstring (date-time)
  • compositionCompositionDto or null
    CompositionDto fields
    • widthinteger
    • heightinteger
    • frameRatenumber
    • durationSecondsnumber
    • frameCountinteger
  • renderableboolean
  • problemsarray of string
  • warningsarray of string
  • soundtrackAudioTrack or null
    AudioTrack fields
    • pathstring
    • offsetSecondsnumber
  • textFittingBaselineVersionIdstring (uuid) or null
  • filesarray of FileDto or null
    FileDto fields
    • pathstring
    • sizeBytesinteger (int64)
    • contentTypestring
    • sha256string
  • namestring or null

Errors

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 413 Payload Too Large
  • 422 Unprocessable Entity
  • 429 Too Many Requests
  • 503 Service Unavailable

application/json · ErrorResponse

  • ApiError fields
    • codestring
    • messagestring

Errors lists the error codes and says when to retry.