Retrieve an asset's usageMenu

Retrieve an asset's usage

GET/v1/assets/{id}/usage

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

Works with integration, agent and partner keys.

Everything whose content contains the file's address, found by the asset id it carries, so raw HTML, CSS url(...) and addresses with a query string count: templates (the draft or any published version), shared blocks, campaigns and journeys in any status, journey enrollments in progress, unsent transactional messages, and the workspace brand, each list at most 50 long, with hasMore when one is longer. Deleting the asset is refused while any of these is listed. Each entry says whether it is locked: one that no edit or delete can free (a sent campaign, an ended journey, enrollments under way, a message about to go) keeps the image, and its bytes count toward storage, until that use ends, if ever.

Path parameters

idstringrequired

The asset's id.

uuid

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}$

Returns

Returns 200 OK with an AssetUsage in data. Otherwise returns an error; Errors lists every code and which to retry.

templatesobject[]required

Templates whose draft or any published version uses the image.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

sharedBlocksobject[]required

Shared blocks that use the image.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

campaignsobject[]required

Campaigns, sent or not, that use the image; locked once sending has started.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

journeysobject[]required

Journeys, in any status, whose steps use the image; locked once ended.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

journeysWithEnrollmentsobject[]required

Journeys with enrollments in progress that follow steps using the image. An enrollment keeps the steps it started with, so these free the image only when those enrollments finish.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

messagesobject[]required

Transactional messages not yet sent that use the image; name is the subject or title. A timed one can be cancelled; an immediate one is locked.

3 child attributes

idstringrequired: uuid
namestringrequired
lockedbooleanrequired: True when no edit or delete can take the image out of this use (a sent campaign, an ended journey, enrollments under way, a message about to go); it is freed only when the use ends, if ever. False when editing or removing it frees the image.

brandKitbooleanrequired

Whether it is the workspace's brand kit logo.

hasMorebooleanrequired

More use it than are listed: each list stops at 50.

curl https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	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.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/assets/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/usage");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

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 · 200

{
  "data": {
    "templates": [
      {
        "id": "0192f3d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "name": "Welcome email",
        "locked": false
      }
    ],
    "sharedBlocks": [],
    "campaigns": [
      {
        "id": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "name": "October newsletter",
        "locked": true
      }
    ],
    "journeys": [],
    "journeysWithEnrollments": [],
    "messages": [],
    "brandKit": false,
    "hasMore": false
  }
}