API reference / Projects

Create a project

POST/v1/projects

Creates an empty project, or one that starts from a ZIP or a copy of a version. Pass zipUploadId, a completed upload whose fileName ends in .zip, to import it as version 1; a ZIP with font files also needs fontLicenseAccepted true. The import is waited for like a package import: 201 with the project, the import's error (the project is not kept), or 202 with the import of a large ZIP still importing. At most 10 imports per workspace wait or run at once (409 import_limit). Pass fromVersionId, any version of the workspace, to duplicate it: the new project starts with that version's files, soundtrack and name, without its history, and its copiedFromVersionId names that version. Send at most one of zipUploadId and fromVersionId. The project starts with one variation, main. A ZIP whose files total more than the plan's project size (limits.maxProjectBytes in the usage) fails with 403 project_too_large, and so does a copy that large unless a head of its source project is at least as large. 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 \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=50" \
  -H "Idempotency-Key: 70337cac-0dc6-34ce-8179-c31f144c64bf" \
  -d '{"name": "Summer sale"}'
import os, requests

response = requests.post(
    f"{os.environ['BLITFRAME']}/projects",
    headers={
        "Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}",
        "Prefer": "wait=50",
        "Idempotency-Key": "70337cac-0dc6-34ce-8179-c31f144c64bf",
    },
    json={"name": "Summer sale"},
)
print(response.json())
const response = await fetch(`${process.env.BLITFRAME}/projects`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`,
    "Content-Type": "application/json",
    Prefer: "wait=50",
    "Idempotency-Key": "70337cac-0dc6-34ce-8179-c31f144c64bf",
  },
  body: JSON.stringify({ name: "Summer sale" }),
});
console.log(await response.json());
<?php
$request = curl_init(getenv("BLITFRAME") . "/projects");
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
        "Content-Type: application/json",
        "Prefer: wait=50",
        "Idempotency-Key: 70337cac-0dc6-34ce-8179-c31f144c64bf",
    ],
    CURLOPT_POSTFIELDS => '{"name": "Summer sale"}',
]);
$response = curl_exec($request);
echo $response;
require "net/http"

uri = URI(ENV["BLITFRAME"] + '/projects')
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer " + ENV["BLITFRAME_API_KEY"]
request["Content-Type"] = "application/json"
request['Prefer'] = 'wait=50'
request['Idempotency-Key'] = '70337cac-0dc6-34ce-8179-c31f144c64bf'
request.body = '{"name": "Summer sale"}'
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(`{"name": "Summer sale"}`)
	request, err := http.NewRequest("POST", os.Getenv("BLITFRAME")+"/projects", 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("Prefer", "wait=50")
	request.Header.Set("Idempotency-Key", "70337cac-0dc6-34ce-8179-c31f144c64bf")
	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");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
request.Headers.Add("Prefer", "wait=50");
request.Headers.Add("Idempotency-Key", "70337cac-0dc6-34ce-8179-c31f144c64bf");
request.Content = new StringContent(
    """
    {"name": "Summer sale"}
    """, 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"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .header("Prefer", "wait=50")
            .header("Idempotency-Key", "70337cac-0dc6-34ce-8179-c31f144c64bf")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {"name": "Summer sale"}
                """))
            .build();
        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Headers

  • AuthorizationBearer Blitframe API keyrequired

    API key from the developer console.

  • Preferstring
  • 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 · CreateProjectRequest

  • namestringrequired
  • zipUploadIdstring (uuid) or null
  • fromVersionIdstring (uuid) or null
  • fontLicenseAcceptedboolean

    Default false

Try it

POST/v1/projects

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

  • 201 Created

application/json · ProjectDto

  • idstring (uuid)
  • namestring
  • createdAtstring (date-time)
  • headVersionIdstring (uuid) or null
  • renderableboolean or null
  • copiedFromVersionIdstring (uuid) or null
  • thumbnailUrlstring or null
  • 202 Accepted

application/json · ZipImportDto

  • idstring (uuid)
  • projectIdstring (uuid)
  • One of queued importing succeeded failed

  • versionIdstring (uuid) or null
  • errorApiError or null
    ApiError fields
    • codestring
    • messagestring
  • createdAtstring (date-time)
  • finishedAtstring (date-time) 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.