Copy an image into the libraryMenu

Copy an image into the library

POST/v1/assets/import

Requires an API key with the templates:write scope. About keys and scopes

Works with integration, agent and partner keys.

A repeat without a key does it again; send Idempotency-Key and a retry within 24 hours replays the first response. About idempotency

Copies the image at a public address into this workspace, checked as an upload is (PNG, JPEG or GIF, at most 2 MB and 25 megapixels), so an email never depends on another site keeping it: images hosted where your email was made before, a logo from your site, or a video block's thumbnail (a YouTube or Vimeo page's address copies its thumbnail). Only public addresses are reached; anything that is not such an image is a 400.

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Idempotency-Keystringoptional

Makes a retry safe: a repeat with the same key and body within 24 hours gets the first response again, with Idempotency-Replay: true. The same key with another request is 409 IDEMPOTENCY_KEY_REUSED; while the first is still running, 409 IDEMPOTENCY_KEY_IN_USE; after an unsafe first request failed or never returned, 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN. Use a new key, such as a UUID, for each new request.

8–255 characters

Request body

urlstringrequired

A public PNG, JPEG or GIF of at most 2 MB, such as a logo on your current site; or a YouTube or Vimeo video page, whose thumbnail is copied.

uri · up to 2,048 characters

namestringoptional

The name the library shows, up to 200 characters; the file's name when omitted.

1–200 characters

Returns

Returns 201 Created with an Asset in data. It can also return 409 Conflict, 413 Payload Too Large or 415 Unsupported Media Type; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

201 CreatedThe copied image and its public URL.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
413 Payload Too LargeThe body is larger than this operation accepts (PAYLOAD_TOO_LARGE).
415 Unsupported Media TypeThe body is not JSON, or not the upload the operation takes (UNSUPPORTED_MEDIA_TYPE).

idstringrequired

uuid

typestringrequired

The kind of file: image. More kinds, such as video, may be added: branch on type and keep the ones you do not know.

one of image

namestringrequired

The name the library shows.

filenamestringrequired

The file's name as uploaded or copied.

urlstringrequired

The file's public address, such as an image src.

uri

mimeTypestringrequired

The file's format.

one of image/png, image/jpeg, image/gif

sizeBytesintegerrequired

File size in bytes.

min > 0

widthintegerrequired

The file's width in px.

min > 0

heightintegerrequired

The file's height in px.

min > 0

createdAtstringrequired

date-time

Headers on `201 Created`

Idempotency-Replaystringoptional

true when this is the stored response to an earlier request with the same key.

one of true

curl -X POST https://api.kirora.io/v1/assets/import \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: importAsset-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme-shop.com/images/acme-logo.png",
    "name": "Acme logo"
  }'

const response = await fetch('https://api.kirora.io/v1/assets/import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "importAsset-0001",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://acme-shop.com/images/acme-logo.png",
    "name": "Acme logo"
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/assets/import",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "importAsset-0001",
    },
    json={
        "url": "https://acme-shop.com/images/acme-logo.png",
        "name": "Acme logo",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "url": "https://acme-shop.com/images/acme-logo.png",
	  "name": "Acme logo"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/assets/import", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "importAsset-0001")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/assets/import");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Headers.Add("Idempotency-Key", "importAsset-0001");
request.Content = new StringContent(
    """
    {
      "url": "https://acme-shop.com/images/acme-logo.png",
      "name": "Acme logo"
    }
    """,
    Encoding.UTF8,
    "application/json");

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 201

{
  "data": {
    "id": "0192f3d2-4d5e-7f60-9b72-8d9e0f1a2b3c",
    "type": "image",
    "name": "Acme logo",
    "filename": "acme-logo.png",
    "url": "https://assets.kirora.io/images/0192f3d2-4d5e-7f60-9b72-8d9e0f1a2b3c.png",
    "mimeType": "image/png",
    "sizeBytes": 18432,
    "width": 600,
    "height": 200,
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}

Copy an image into the library

Header parameters

Request body

Returns

Headers on 201 Created

Headers on `201 Created`