Describe an attribute keyMenu

Describe an attribute key

PUT/v1/attributes/{key}

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

Works with integration, agent and partner keys.

Safe to retry: a repeat sets the same values again. About idempotency

Sets what an attribute key means, in the workspace's words, or removes it with null. A key no contact carries yet may be described too; it shows in the key list once contacts carry it. An agent key may describe keys: nothing is sent or changed on a contact.

Path parameters

keystringrequired

The attribute key, as listAttributes returns it, URL-encoded (a key in any language is percent-encoded as UTF-8). Matched in Unicode NFC, as keys are stored, so a composed and a decomposed "é" are the same key.

pattern ^[\p{L}\p{N}\p{M}_.-]{1,64}$

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

Request body

descriptionstring | nullrequired

What the key means, at most 255 characters: shown in the Data index's attribute list, and read by Kiro. null removes it.

1–255 characters

Returns

Returns 200 OK with an AttributeDescription 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 key's description.
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).

keystringrequired
descriptionstring | nullrequired

curl -X PUT https://api.kirora.io/v1/attributes/plan \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "The billing plan the contact pays for."
  }'

const response = await fetch('https://api.kirora.io/v1/attributes/plan', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": "The billing plan the contact pays for."
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.put(
    "https://api.kirora.io/v1/attributes/plan",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "description": "The billing plan the contact pays for.",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "description": "The billing plan the contact pays for."
	}`)
	req, err := http.NewRequest("PUT", "https://api.kirora.io/v1/attributes/plan", 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.Put, "https://api.kirora.io/v1/attributes/plan");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "description": "The billing plan the contact pays for."
    }
    """,
    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": {
    "key": "plan",
    "description": "The billing plan the contact pays for."
  }
}