Managed assets

Copy one external image into Batch Relay-managed fulfillment storage

Requires print_orders:write and an Idempotency-Key up to 200 characters. Anonymous Test Mode sessions use a separate managed-ingest request limit, not byte metering. Supply exactly one source: an externally routable HTTPS url is downloaded with SSRF protections, content-validated, SHA-256-addressed, and written immutably to the fulfillment R2 scope; an asset_id is resolved as a ready unexpired same-account external asset or a finalized same-studio platform image and is never copied. Source URLs are not fulfillment URLs and are not retained in the managed asset record.

POST

assets

ingest

curl --request POST \
  --url https://api.batchrelay.com/v1/assets/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "url": "<string>",
  "asset_id": "<string>",
  "original_filename": "<string>"
}
'

import requests

url = "https://api.batchrelay.com/v1/assets/ingest"

payload = {
    "url": "<string>",
    "asset_id": "<string>",
    "original_filename": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({url: '<string>', asset_id: '<string>', original_filename: '<string>'})
};

fetch('https://api.batchrelay.com/v1/assets/ingest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.batchrelay.com/v1/assets/ingest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'asset_id' => '<string>',
    'original_filename' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.batchrelay.com/v1/assets/ingest"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.batchrelay.com/v1/assets/ingest")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.batchrelay.com/v1/assets/ingest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "asset_id": "<string>",
  "byte_size": 2,
  "content_type": "image/jpeg",
  "format": "jpeg",
  "original_filename": "<string>",
  "pixel_height": 2,
  "pixel_width": 2,
  "reused": true,
  "sha256": "<string>",
  "storage_scope": "studio"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Batch Relay scoped API key or an anonymous Test Mode session. Scope names document required capabilities. Anonymous sessions are sandbox-only and do not authorize studio, event, billing, or Live Mode operations.

Headers

Idempotency-Key

string

required

Required stable key for the managed ingestion request; reuse with a different URL/source is rejected.

Required string length: 1 - 200

X-BatchRelay-Client-Surface

string

Untrusted optional analytics hint naming the calling client surface. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100

X-BatchRelay-Client-Version

string

Untrusted optional analytics hint naming the calling client version. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100

X-BatchRelay-Invocation-Mode

string

Untrusted optional analytics hint naming the invocation mode. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100

Body

application/json

Option 1
Option 2

url

string<uri>

required

One external source. It is downloaded and never retained as the fulfillment URL.

Pattern: ^https://

asset_id

string

One already-finalized Batch Relay or platform image asset. It is resolved and reused without a byte copy.

original_filename

string

Maximum string length: 255

Response

Managed immutable asset

asset_id

string

required

Opaque identifier for later managed-asset attachment.

byte_size

integer

required

Required range: x >= 1

content_type

enum<string>

required

Available options:

image/jpeg,

image/png,

image/tiff,

image/webp

format

enum<string>

required

Available options:

jpeg,

png,

tiff,

webp

original_filename

string

required

pixel_height

integer

required

Required range: x >= 1

pixel_width

integer

required

Required range: x >= 1

reused

boolean

required

True when the same immutable object already existed or a finalized asset_id was reused.

sha256

string

required

Pattern: ^[a-f0-9]{64}$

storage_scope

enum<string>

required

External URL ingress always returns fulfillment; private delivery uses this scope plus object-key lookup.

Available options:

studio,

fulfillment

Copy one external image into Batch Relay-managed fulfillment storage

curl --request POST \
  --url https://api.batchrelay.com/v1/assets/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "url": "<string>",
  "asset_id": "<string>",
  "original_filename": "<string>"
}
'

import requests

url = "https://api.batchrelay.com/v1/assets/ingest"

payload = {
    "url": "<string>",
    "asset_id": "<string>",
    "original_filename": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({url: '<string>', asset_id: '<string>', original_filename: '<string>'})
};

fetch('https://api.batchrelay.com/v1/assets/ingest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.batchrelay.com/v1/assets/ingest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'asset_id' => '<string>',
    'original_filename' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.batchrelay.com/v1/assets/ingest"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.batchrelay.com/v1/assets/ingest")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.batchrelay.com/v1/assets/ingest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"asset_id\": \"<string>\",\n  \"original_filename\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "asset_id": "<string>",
  "byte_size": 2,
  "content_type": "image/jpeg",
  "format": "jpeg",
  "original_filename": "<string>",
  "pixel_height": 2,
  "pixel_width": 2,
  "reused": true,
  "sha256": "<string>",
  "storage_scope": "studio"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

{
  "code": "<string>",
  "docs_url": "<string>",
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>"
}

System

Authentication

Anonymous sessions

API accounts

API keys

Managed assets

Browser previews

Catalog

Event team changes

Studio management

Print orders

Template renders

Studio assets

Studio audit

Asset sessions

Assets

Studio catalog assets

Checkout links

Image imports

Studio messages

Studio offers

Studio catalog

Sandbox promotions

Storefront

Templates

Copy one external image into Batch Relay-managed fulfillment storage

Authorizations

Headers

Body

Response