Key Sets

Endpointhttps://api.kontorion.eu/v1

Key sets: the org-global registries of pricing keys that rate tables and prices resolve against.

List key sets

GET

https://api.kontorion.eu/v1

/key-sets

Lists the organization's key sets with product usage counts.

List key sets › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List key sets › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List key sets › Responses

array | null · required

object · required

GET/key-sets

curl --request GET \
  --url https://api.kontorion.eu/v1/key-sets

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "deleted_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "entries": [
        {
          "created_at": "2024-08-25T15:00:00Z",
          "display_name": "display_name",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "key": "key",
          "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "metadata": {
            "key": {}
          },
          "status": "active",
          "tags": [
            "string"
          ],
          "updated_at": "2024-08-25T15:00:00Z"
        }
      ],
      "entry_count": 0,
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "lifecycle_status": "active",
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_count": 0,
      "slug": "slug",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a key set

POST

https://api.kontorion.eu/v1

/key-sets

Creates an org-global key set, optionally seeding entries in the same call (CSV-import flow).

Create a key set › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a key set › Request Body

description

string · maxLength: 2000

Optional description of the set.

array | null · maxItems: 1000

Optional keys to seed the set with in the same call; validated like UpsertEntries.

name

string · maxLength: 200

Display name for the new key set.

slug

string · maxLength: 100

URL-safe unique identifier for the new key set, matching ^[a-z0-9][a-z0-9_-]{0,63}$.

Example: regions

Create a key set › Responses

Created

object · required

POST/key-sets

curl --request POST \
  --url https://api.kontorion.eu/v1/key-sets \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "description": "description",
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ],
  "name": "name",
  "slug": "regions"
}
'

shell

Example Request Body

{
  "description": "description",
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ],
  "name": "name",
  "slug": "regions"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a key set

GET

https://api.kontorion.eu/v1

/key-sets/{id}

Returns one key set with all entries.

Get a key set › path Parameters

id

string · uuid · required

Key set ID

Get a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a key set › Responses

object · required

GET/key-sets/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/key-sets/:id

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update a key set

PATCH

https://api.kontorion.eu/v1

/key-sets/{id}

Updates name/description (bookkeeping fields; slug is immutable).

Update a key set › path Parameters

id

string · uuid · required

Key set ID

Update a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a key set › Request Body

description

string · maxLength: 2000

New description; omit to leave unchanged.

name

string · maxLength: 200

New display name; omit to leave unchanged.

Update a key set › Responses

object · required

PATCH/key-sets/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/key-sets/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "description",
  "name": "name"
}
'

shell

Example Request Body

{
  "description": "description",
  "name": "name"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Archive a key set (terminal)

POST

https://api.kontorion.eu/v1

/key-sets/{id}/archive

Archives a key set and returns 200 with the archived key set. Refused (409) while any product references it; the references endpoint lists the blockers.

Archive a key set (terminal) › path Parameters

id

string · uuid · required

Key set ID

Archive a key set (terminal) › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Archive a key set (terminal) › Responses

object · required

POST/key-sets/{id}/archive

curl --request POST \
  --url https://api.kontorion.eu/v1/key-sets/:id/archive \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Upsert key set entries

PUT

https://api.kontorion.eu/v1

/key-sets/{id}/entries

Bulk-upserts entries by key: existing keys are overwritten (display name, status, tags, metadata), new keys are added. Retire keys by upserting status=retired.

Upsert key set entries › path Parameters

id

string · uuid · required

Key set ID

Upsert key set entries › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Upsert key set entries › Request Body

array | null · maxItems: 1000

The keys to upsert; each existing key is overwritten and new keys are added.

Upsert key set entries › Responses

object · required

PUT/key-sets/{id}/entries

curl --request PUT \
  --url https://api.kontorion.eu/v1/key-sets/:id/entries \
  --header 'Content-Type: application/json' \
  --data '
{
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ]
}
'

shell

Example Request Body

{
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ]
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List products referencing a key set

GET

https://api.kontorion.eu/v1

/key-sets/{id}/references

Returns the products linked to the key set — the archive/retire blast radius.

List products referencing a key set › path Parameters

id

string · uuid · required

Key set ID

List products referencing a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List products referencing a key set › Responses

array | null · required

object · required

Costs Pricing/Resolutions

Kontorion Billing API

Key Sets

Endpointhttps://api.kontorion.eu/v1

Key sets: the org-global registries of pricing keys that rate tables and prices resolve against.

List key sets

GET

https://api.kontorion.eu/v1

/key-sets

Lists the organization's key sets with product usage counts.

List key sets › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List key sets › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List key sets › Responses

array | null · required

object · required

GET/key-sets

curl --request GET \
  --url https://api.kontorion.eu/v1/key-sets

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "deleted_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "entries": [
        {
          "created_at": "2024-08-25T15:00:00Z",
          "display_name": "display_name",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "key": "key",
          "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "metadata": {
            "key": {}
          },
          "status": "active",
          "tags": [
            "string"
          ],
          "updated_at": "2024-08-25T15:00:00Z"
        }
      ],
      "entry_count": 0,
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "lifecycle_status": "active",
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_count": 0,
      "slug": "slug",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a key set

POST

https://api.kontorion.eu/v1

/key-sets

Creates an org-global key set, optionally seeding entries in the same call (CSV-import flow).

Create a key set › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a key set › Request Body

description

string · maxLength: 2000

Optional description of the set.

array | null · maxItems: 1000

Optional keys to seed the set with in the same call; validated like UpsertEntries.

name

string · maxLength: 200

Display name for the new key set.

slug

string · maxLength: 100

URL-safe unique identifier for the new key set, matching ^[a-z0-9][a-z0-9_-]{0,63}$.

Example: regions

Create a key set › Responses

Created

object · required

POST/key-sets

curl --request POST \
  --url https://api.kontorion.eu/v1/key-sets \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "description": "description",
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ],
  "name": "name",
  "slug": "regions"
}
'

shell

Example Request Body

{
  "description": "description",
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ],
  "name": "name",
  "slug": "regions"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a key set

GET

https://api.kontorion.eu/v1

/key-sets/{id}

Returns one key set with all entries.

Get a key set › path Parameters

id

string · uuid · required

Key set ID

Get a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a key set › Responses

object · required

GET/key-sets/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/key-sets/:id

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update a key set

PATCH

https://api.kontorion.eu/v1

/key-sets/{id}

Updates name/description (bookkeeping fields; slug is immutable).

Update a key set › path Parameters

id

string · uuid · required

Key set ID

Update a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a key set › Request Body

description

string · maxLength: 2000

New description; omit to leave unchanged.

name

string · maxLength: 200

New display name; omit to leave unchanged.

Update a key set › Responses

object · required

PATCH/key-sets/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/key-sets/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "description",
  "name": "name"
}
'

shell

Example Request Body

{
  "description": "description",
  "name": "name"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Archive a key set (terminal)

POST

https://api.kontorion.eu/v1

/key-sets/{id}/archive

Archives a key set and returns 200 with the archived key set. Refused (409) while any product references it; the references endpoint lists the blockers.

Archive a key set (terminal) › path Parameters

id

string · uuid · required

Key set ID

Archive a key set (terminal) › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Archive a key set (terminal) › Responses

object · required

POST/key-sets/{id}/archive

curl --request POST \
  --url https://api.kontorion.eu/v1/key-sets/:id/archive \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Upsert key set entries

PUT

https://api.kontorion.eu/v1

/key-sets/{id}/entries

Bulk-upserts entries by key: existing keys are overwritten (display name, status, tags, metadata), new keys are added. Retire keys by upserting status=retired.

Upsert key set entries › path Parameters

id

string · uuid · required

Key set ID

Upsert key set entries › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Upsert key set entries › Request Body

array | null · maxItems: 1000

The keys to upsert; each existing key is overwritten and new keys are added.

Upsert key set entries › Responses

object · required

PUT/key-sets/{id}/entries

curl --request PUT \
  --url https://api.kontorion.eu/v1/key-sets/:id/entries \
  --header 'Content-Type: application/json' \
  --data '
{
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ]
}
'

shell

Example Request Body

{
  "entries": [
    {
      "display_name": "display_name",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "status": "status",
      "tags": [
        "string"
      ]
    }
  ]
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "entries": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "key": "key",
        "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "metadata": {
          "key": {}
        },
        "status": "active",
        "tags": [
          "string"
        ],
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "entry_count": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle_status": "active",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_count": 0,
    "slug": "slug",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List products referencing a key set

GET

https://api.kontorion.eu/v1

/key-sets/{id}/references

Returns the products linked to the key set — the archive/retire blast radius.

List products referencing a key set › path Parameters

id

string · uuid · required

Key set ID

List products referencing a key set › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List products referencing a key set › Responses

array | null · required

object · required

Costs Pricing/Resolutions