Upload Brand Image
Learn how to upload brand assets to your workspace
Updated
/v1/brand-assets/images/addcurl -X POST "https://api.orshot.com/v1/brand-assets/images/add" \
-H "Authorization: Bearer <ORSHOT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"file": "<FILE>",
"fileName": "<FILE_NAME>",
"fileType": "<FILE_TYPE>",
"tags": []
}'const res = await fetch("https://api.orshot.com/v1/brand-assets/images/add", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <ORSHOT_API_KEY>",
},
body: JSON.stringify({
"file": "<FILE>",
"fileName": "<FILE_NAME>",
"fileType": "<FILE_TYPE>",
"tags": []
}),
});
const data = await res.json();import requests
response = requests.post(
"https://api.orshot.com/v1/brand-assets/images/add",
headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
json={
"file": "<FILE>",
"fileName": "<FILE_NAME>",
"fileType": "<FILE_TYPE>",
"tags": []
},
)
data = response.json()$ch = curl_init("https://api.orshot.com/v1/brand-assets/images/add");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer <ORSHOT_API_KEY>",
"Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"file" => "<FILE>",
"fileName" => "<FILE_NAME>",
"fileType" => "<FILE_TYPE>",
"tags" => []
]));
$data = json_decode(curl_exec($ch), true);
curl_close($ch);require "net/http"
require "json"
uri = URI("https://api.orshot.com/v1/brand-assets/images/add")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
req["Content-Type"] = "application/json"
req.body = {
"file": "<FILE>",
"fileName": "<FILE_NAME>",
"fileType": "<FILE_TYPE>",
"tags": []
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)Overview#
This endpoint allows you to upload new brand assets (images) to your workspace. You can upload images from a URL or as a base64-encoded string.
https://api.orshot.com/v1/brand-assets/images/addRequest#
await fetch("https://api.orshot.com/v1/brand-assets/images/add", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <ORSHOT_API_KEY>",
},
body: JSON.stringify({
file: "https://example.com/path/to/image.png", // supports base64, url or binary
fileName: "company-logo.png", // optional
fileType: "image/png", // optional
tags: ["logo", "brand"], // optional
}),
});await fetch("https://api.orshot.com/v1/brand-assets/images/add", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <ORSHOT_API_KEY>",
},
body: JSON.stringify({
file: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
fileName: "product-image.png", // optional
meta: { // optional
description: "Product image for website",
category: "products"
}
}),
});{
"data": {
"asset": {
"id": 102,
"created_at": "2025-09-11T10:15:30.123Z",
"direct_url": "https://storage.orshot.com/brand-assets/workspace_id/company-logo.png",
"file_name": "company-logo.png",
"file_size": 24680,
"workspace_id": 50,
"user_id": "abcdef01-2345-6789-abcd-ef0123456789"
},
"url": "https://storage.orshot.com/brand-assets/workspace_id/company-logo.png"
}
}Request Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
file | String | Yes | URL, binary or base64-encoded string of the image |
fileName | String | No | Custom filename for the asset (default: auto-generated based on timestamp) |
fileType | String | No | MIME type of the file (e.g., "image/png"). If not provided, it will be detected from the file |
tags | String[] | No | Array of tags to associate with the asset (e.g., ["logo", "brand"]) |
meta | Object | No | Arbitrary metadata to store with the asset (e.g., { "source": "product-catalog" }) |
Supported Image Formats#
- PNG (
image/png) - JPEG (
image/jpeg) - WebP (
image/webp) - SVG (
image/svg+xml) - GIF (
image/gif)
Notes#
- Images are automatically optimized and resized if needed (maximum dimensions: 2000x2000 pixels)
- Maximum file size: 10MB
- SVG files are not optimized to preserve their vector format
Error responses#
Input problems return 400 with a plain-language error and, for the two cases agents hit most, a stable code:
IMAGE_NOT_AN_IMAGE: the bytes carry no PNG, JPEG, WebP, GIF or SVG signature. Usually a filename, a description, or placeholder text was sent instead of the file, or a URL served an HTML page.IMAGE_DATA_INCOMPLETE: the data starts as a real image file but ends early. The base64 was cut off in transit, the URL served a partial file, or the upload stopped before the end. Theerrornames the fix for how the file was sent.
Hosted chat clients such as ChatGPT and Claude.ai cannot send file bytes, so a base64 file from them is almost always cut off. Pass a publicly reachable image URL instead.
Query Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
embedId | String | No | Embed instance ID. Pair with embedUserId to scope this call to one embed user |
embedUserId | String | No | The same userId your app passes to the embed URL. Requires embedId |
Per-User Libraries#
Pass embedId and embedUserId together to create the image in that embed user's private library instead of the shared workspace library. This is how one embed serves many brands or tenants, each with its own brand space.
Omit them and this endpoint behaves exactly as documented above. See Per-User Brand Assets for the full picture.
Rate Limits#
- 30 requests per minute per endpoint
Ready to automate?
Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.
Get your API key- Image, PDF and video generation via API
- Visual editor with AI and smart layouts
- Zapier, Make, MCP and 50+ integrations
- White-label embed for your own app
- 30 free credits — no credit card required