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 keyrequiredAPI key from the developer console.
Idempotency-KeystringOptional. 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 nullmessagestring or nullfilesarray of EditFile or nullEditFile fields
pathstringrequiredcontentstring or nullcontentBase64string or nulluploadIdstring (uuid) or nullfromVersionIdstring (uuid) or nullfromPathstring or null
deletearray of string or nullrestoreFromVersionIdstring (uuid) or nullnamestring or nullfontLicenseAcceptedbooleanDefault
falsesoundtrackAudioTrack or nullAudioTrack fields
pathstringrequiredoffsetSecondsnumberDefault
0
textFittingBaselineVersionIdstring (uuid) or nullreplacementsarray of Replacement or nullReplacement fields
variationstring or null
Responses
- 200 OK
- 201 Created
application/json · VersionDto
idstring (uuid)projectIdstring (uuid)parentVersionIdstring (uuid) or nullnumberintegermessagestringcreatedAtstring (date-time)compositionCompositionDto or nullCompositionDto fields
widthintegerheightintegerframeRatenumberdurationSecondsnumberframeCountinteger
renderablebooleanproblemsarray of stringwarningsarray of stringsoundtrackAudioTrack or nullAudioTrack fields
pathstringoffsetSecondsnumber
textFittingBaselineVersionIdstring (uuid) or nullfilesarray of FileDto or nullFileDto fields
pathstringsizeBytesinteger (int64)contentTypestringsha256string
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
errorApiErrorApiError fields
codestringmessagestring
Errors lists the error codes and says when to retry.