Share links

View as Markdown

A share link is a public web page that plays one project's video. Send it to a client or a teammate: they watch it in the browser, without a Code Artworks account.

Share links come with plans that include them (pricing); limits.shareLinks in GET /v1/usage says whether yours does. On another plan, creating one returns 403 plan_feature, and the workspace's existing links stop playing until it is on such a plan again. You can still list and revoke them.

The example reads BLITFRAME, BLITFRAME_API_KEY and PROJECT_ID from the environment. Set the first two as in the quickstart, and PROJECT_ID to the id of one of your projects.

curl -s -X POST $BLITFRAME/projects/$PROJECT_ID/share-links \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" -d '{}' | jq -r .url
import os, requests

project_id = os.environ["PROJECT_ID"]
response = requests.post(
    f"{os.environ['BLITFRAME']}/projects/{project_id}/share-links",
    headers={"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"},
    json={},
)
print(response.json()["url"])
const projectId = process.env.PROJECT_ID;
const response = await fetch(`${process.env.BLITFRAME}/projects/${projectId}/share-links`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log((await response.json()).url);
<?php
$projectId = getenv("PROJECT_ID");
$ch = curl_init(getenv("BLITFRAME") . "/projects/$projectId/share-links");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BLITFRAME_API_KEY"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => "{}",
]);
echo json_decode(curl_exec($ch), true)["url"], "\n";
require "net/http"
require "json"

project_id = ENV["PROJECT_ID"]
uri = URI("#{ENV["BLITFRAME"]}/projects/#{project_id}/share-links")
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.post(uri.request_uri, "{}", headers)
end
puts JSON.parse(response.body)["url"]
package main

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

func main() {
	projectID := os.Getenv("PROJECT_ID")
	url := os.Getenv("BLITFRAME") + "/projects/" + projectID + "/share-links"
	req, err := http.NewRequest("POST", url, strings.NewReader("{}"))
	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)
	}
	fmt.Println(out["url"])
}
using System.Net.Http.Json;
using System.Text.Json.Nodes;

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

var response = await http.PostAsync($"{api}/projects/{projectId}/share-links", JsonContent.Create(new { }));
var link = await response.Content.ReadFromJsonAsync<JsonNode>();
Console.WriteLine((string?)link?["url"]);
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;

public class Example {
    public static void main(String[] args) throws Exception {
        String projectId = System.getenv("PROJECT_ID");
        HttpRequest request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + "/projects/" + projectId + "/share-links"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{}"))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(new ObjectMapper().readTree(response.body()).get("url").asText());
    }
}

The example prints the link's url, the page to send. The response is 201 Created with the whole link:

{
  "id": "q3Zb0yHn4t7mTq2cV9xL1w",
  "projectId": "5405…",
  "versionId": null,
  "variation": "main",
  "quality": "high",
  "url": "https://blitframe.codeartworks.com/r/q3Zb0yHn4t7mTq2cV9xL1w",
  "createdAt": "2026-11-05T10:00:00+00:00"
}

POST /v1/projects/{projectId}/share-links takes these fields, all optional:

Field Values Default
quality low, medium, high or extraHigh, as for renders high
versionId A version of the project to pin the link to, or null to follow a head null
variation Without versionId: the variation whose head the link follows main

A link that follows a head always plays that variation's latest version. Pin it to keep showing one version after the project is edited again. Any version of the project can be pinned, including the version a render with replacements made.

In the response, variation names the variation a link follows, such as main. It is null for a link pinned to a version. A project can have up to 50 links, across all its variations. Another returns 409 too_many_share_links.

What the page plays

The page plays a succeeded MP4 or HLS render of the version at the link's quality: the head, or the pinned version. If there are several, it plays the newest. Only plain renders count: no name, the version's own soundtrack (no audio override), and your plan's current watermark setting.

If there is no such render yet, the page shows a Play button:

  • Opening the page renders nothing, so the previews chat apps make of a pasted link cost nothing.
  • The first visitor to press Play queues one HLS render in your workspace. Your workspace is charged its render seconds, and the visitor pays nothing. Everyone who presses Play later, or at the same time, waits for that same render.
  • The page refreshes by itself until the video is ready.

Editing the variation a link follows moves its head, so the next press of Play renders the new version once. Pin the link if you don't want visitors to render new versions.

The page shows only the video and its poster: no project names, file names or workspace details. Link previews show the poster once the video exists. Search engines do not index the page.

If the page says the video is not available, when the video is not available says why and how to fix it.

List and revoke

Method Path Does
GET /v1/projects/{projectId}/share-links The project's links, oldest first
DELETE /v1/share-links/{linkId} Revoke a link. Returns 204.

A revoked link's page answers 404. Someone already watching can keep playing for at most the video's length plus two minutes. Renders the link made stay in your workspace.

Deleting the project also removes its links. Deleting a variation removes the links that follow its head. Links pinned to one of its versions keep playing.

Agents use the MCP tools create_share_link, list_share_links and delete_share_link. See MCP for agents.

Details

When the video is not available

If the render fails or is cancelled, the page says so, and the next press of Play tries again.

After two failed or cancelled renders of the same version and quality started from share pages since the link was created, Play stops rendering it. The page then says the video is not available. Renders you start yourself don't count. To fix it, do one of these:

  • render the version yourself at the link's quality (the page picks that render up),
  • edit the variation the link follows,
  • create a new link.

The page also says the video is not available when:

  • the project has no version yet,
  • the version cannot be rendered, or is over your plan limits,
  • your workspace cannot render right now: no free trial, render seconds used up, trial or plan ended, a failed payment still unpaid 3 days after the period ended, or a disputed payment.

Refused requests

  • variation with versionId is 400 invalid_request.
  • A versionId that is not a version of this project is 404 not_found.
  • A quality other than low, medium, high and extraHigh is 400 invalid_request.
  • A variation the project doesn't have is 404 not_found.