Merge a tag into anotherMenu

Merge a tag into another

POST/v1/tags/{id}/merge

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

Works with integration, agent and partner keys.

A repeat after success returns 404 or 409: treat that as done. About idempotency

Moves every item carrying this tag onto targetTagId, then deletes this tag, in one step: how "BF" and "Black Friday" become one. An item already carrying both keeps one. Rules that name this tag (segments, campaign audiences, journey filters, goal populations, block conditions in designs) are pointed at the target in the same step, so a rule that named either tag now matches the items of both. Since that can change who a rule reaches, an agent key is refused with 403 AGENT_KEY_REFUSED when a rule names either tag. Merging a tag into itself is refused with 400.

Path parameters

idstringrequired

The tag'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}$

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

targetTagIdstringrequired

The tag that takes over every item, and survives the merge.

uuid

Returns

Returns 200 OK with a Tag 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.

200 OKThe target tag, with its usage after the merge.
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

namestringrequired

usageobjectrequired

How many items of each kind carry the tag.

4 child attributes

campaignsintegerrequired: min 0
journeysintegerrequired: min 0
segmentsintegerrequired: min 0
templatesintegerrequired: min 0

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

Headers on `200 OK`

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/tags/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/merge \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetTagId": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f"
  }'

const response = await fetch('https://api.kirora.io/v1/tags/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/merge', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "targetTagId": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f"
  }),
});
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/tags/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/merge",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "targetTagId": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "targetTagId": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/tags/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/merge", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	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/tags/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/merge");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "targetTagId": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f"
    }
    """,
    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 · 200

{
  "data": {
    "id": "0192f3e0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "name": "Black Friday",
    "usage": {
      "campaigns": 6,
      "journeys": 1,
      "segments": 3,
      "templates": 3
    },
    "createdAt": "2026-10-01T09:30:00.000Z",
    "updatedAt": "2026-10-02T14:05:00.000Z"
  }
}

Merge a tag into another

Path parameters

Header parameters

Request body

Returns

Headers on 200 OK

Headers on `200 OK`