HIVE Docs
Explore HIVE

API reference

The HIVE API is organised around resources, uses standard HTTP methods and status codes, and accepts and returns JSON. Every request is made over HTTPS to https://api.hive.clerktree.com/v1.

Authentication

Send an API key as a bearer token: Authorization: Bearer $HIVE_API_KEY. A few administrative operations need a signed-in user instead and are marked User session.

Versioning

Pin a version with the Hive-Version header (current: 2026-11-01). Without it, your organisation's pinned version applies. See API versions.

Errors

Errors are problem objects with a stable code; every code has its own page under Error codes.

Retries

Send an Idempotency-Key with a create or action and retry it safely. Updates take If-Match with the version you read.

Health

API health#

GET/v1/health

No authentication

Returns

Process is live

curl https://api.hive.clerktree.com/v1/health \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "health",
  "status": "ok"
}

Specification

The AsyncAPI document#

GET/v1/asyncapi.json

The AsyncAPI 3 document of the public events and webhooks of the latest released dated version, or of the version in the query parameter. Public, unauthenticated, cacheable.

No authentication

Parameters

versionquery · string
A released dated version. Absent means the latest released version.

Returns

The document, without internal operations, tenant data or secrets

Errors

unsupported_versionnot_found

curl https://api.hive.clerktree.com/v1/asyncapi.json \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "asyncapi": "3.0.0",
  "channels": {},
  "info": {
    "title": "HIVE API",
    "version": "2026-11-01"
  }
}

The OpenAPI document#

GET/v1/openapi.json

The bundled OpenAPI 3.1 document of the latest released dated version, or of the version in the query parameter. Public, unauthenticated, cacheable.

No authentication

Parameters

versionquery · string
A released dated version. Absent means the latest released version.

Returns

The document, without internal operations, tenant data or secrets

Errors

unsupported_versionnot_found

curl https://api.hive.clerktree.com/v1/openapi.json \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "info": {
    "title": "HIVE API",
    "version": "2026-11-01"
  },
  "openapi": "3.1.0",
  "paths": {}
}

API versions

List the API versions#

GET/v1/api-versions

Every dated version with its status, dates and changelog URL. The registry is public and tenant-independent; only pinned_by_tenant depends on the caller.

Permission api_version.read

Returns

The versions

Errors

unavailable

curl https://api.hive.clerktree.com/v1/api-versions \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "object": "api_version",
      "changelog_url": "https://docs.hive.clerktree.com/changes/2026-11-01",
      "deprecated_on": null,
      "pinned_by_tenant": true,
      "released_on": "2026-11-01",
      "status": "current",
      "sunset_on": null,
      "version": "2026-11-01"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Change the tenant pin#

POST/v1/api-versions/pin

Pins the tenant to a served version, newer or older, or with dry_run true lists what the change affects. The pin takes effect within 60 seconds and is audited. Human only; the system never changes a pin itself.

User sessionPermission api_version.updateIdempotent with keyPeople only

Parameters

Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Body

dry_runboolean
True lists the changes and the calls of the last 30 days they affect, and changes nothing
versionstringrequired
A served version of the registry, newer or older than the current pin

Returns

The preview of a dry run, or the new pin

Errors

unsupported_versionunavailableconflict

curl -X POST https://api.hive.clerktree.com/v1/api-versions/pin \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "version": "2027-04-01"
}'
Response200 OK
{
  "object": "api_version_pin_preview",
  "affected_calls_last_30_days": [
    {
      "calls": 42,
      "operation_id": "alarm_list",
      "principal_id": "sva_01jc8z3k5me9rt7q2v4x6b0dnh",
      "version": "2026-11-01"
    }
  ],
  "changes": [
    {
      "id": "2027-04-01-alarm-priority-enum",
      "title": "Alarm priority is now an enumeration"
    }
  ],
  "from_version": "2026-11-01",
  "to_version": "2027-04-01"
}

Retrieve one API version#

GET/v1/api-versions/{version}

One version with its changes.

Permission api_version.read

Parameters

versionpath · stringrequired
A dated API version

Returns

The version

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/api-versions/string \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "api_version",
  "changelog_url": "https://docs.hive.clerktree.com/changes/2026-11-01",
  "changes": [
    {
      "id": "2027-04-01-alarm-priority-enum",
      "affected_objects": [
        "alarm"
      ],
      "affected_operations": [
        "alarm_list"
      ],
      "description": "The priority of an alarm is the string low, medium, high or critical instead of the integer 1 to 4.",
      "is_security_exception": false,
      "reversible": true,
      "title": "Alarm priority is now an enumeration",
      "title_i18n": {
        "de": "Alarmpriorität ist jetzt eine Aufzählung",
        "en": "Alarm priority is now an enumeration"
      }
    }
  ],
  "deprecated_on": null,
  "pinned_by_tenant": true,
  "released_on": "2026-11-01",
  "status": "current",
  "sunset_on": null,
  "version": "2026-11-01"
}

API keys

List the API keys#

GET/v1/api-keys

The API keys of the tenant, newest first; filter by service_account_id. No response holds a secret.

Permission api_key.list

Parameters

limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of API keys

Errors

unavailable

curl https://api.hive.clerktree.com/v1/api-keys?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "key_01m71xxng7fzrvspnkgtw1t2km",
      "object": "api_key",
      "allowed_cidrs": [
        "203.0.113.0/24"
      ],
      "created_at": "2026-11-11T09:30:00Z",
      "created_by": "usr_01m71xxng7fzrvspnkgtw1t2kg",
      "env": "live",
      "expires_at": "2027-11-11T09:30:00Z",
      "hint": "EzXy",
      "last_used_at": null,
      "name": "MES feed",
      "previous_secret_expires_at": null,
      "rotated_at": null,
      "scopes": [
        "asset.read",
        "signal.query"
      ],
      "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
      "status": "active",
      "updated_at": "2026-11-11T09:30:00Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Create an API key#

POST/v1/api-keys

Creates a key for a service account and returns it once, in the response. Needs a user with a recent step-up authentication; a service account cannot create keys. A scope that is a human-only permission answers 400 human_only_permission.

User sessionPermission api_key.createIdempotent with keyStep-up authentication

Parameters

Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Body

allowed_cidrsarray of strings
The address ranges the key may be used from; empty means any address (at most 20).
envenumrequired
The environment of the key: live or test. One of live, test.
expires_atstring (date-time)
When the key stops working; 365 days from now when omitted, at most 730 days.
namestringrequired
A name for the key, for example the system that uses it.
scopesarray of stringsrequired
The permissions the key can use at most; patterns such as work_order.* expand without human-only permissions, an explicit human-only permission is refused.
service_account_idstringrequired
The service account the key belongs to.

Returns

The new key, with its secret

Errors

not_foundconflictlimit_exceededstep_up_requiredpermission_deniedunavailable

curl -X POST https://api.hive.clerktree.com/v1/api-keys \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "env": "live",
  "name": "MES feed",
  "scopes": [
    "signal.query",
    "asset.read",
    "work_order.*"
  ],
  "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj"
}'
Response201 Created
{
  "id": "key_01m71xxng7fzrvspnkgtw1t2km",
  "object": "api_key",
  "allowed_cidrs": [
    "203.0.113.0/24"
  ],
  "created_at": "2026-11-11T09:30:00Z",
  "created_by": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "env": "live",
  "expires_at": "2027-11-11T09:30:00Z",
  "hint": "EzXy",
  "last_used_at": null,
  "name": "MES feed",
  "previous_secret_expires_at": null,
  "rotated_at": null,
  "scopes": [
    "asset.read",
    "signal.query"
  ],
  "secret": "hive_live_01m71xxng7fzrvspnkgtw1t2km_Zk3p9Qd7LmW2xVb8Nc4TgYh6JrAe1UoSi5Fa0KwDqEzXy",
  "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Revoke an API key#

DELETE/v1/api-keys/{id}

Revokes the key for good: it stops working everywhere within seconds and cannot be restored; create a new key instead.

User sessionPermission api_key.revokeRequires If-Match

Parameters

idpath · stringrequired
The ID of an API key of the tenant. Any other ID answers like a missing one.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Returns

The key is revoked

Errors

not_foundunavailable

# ETAG: the ETag header of your last read of this resource
curl -X DELETE https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG"
Response204 No Content
No body

Get an API key#

GET/v1/api-keys/{id}

One API key of the tenant, with its hint and metadata and without its secret.

Permission api_key.get

Parameters

idpath · stringrequired
The ID of an API key of the tenant. Any other ID answers like a missing one.

Returns

The key

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "key_01m71xxng7fzrvspnkgtw1t2km",
  "object": "api_key",
  "allowed_cidrs": [
    "203.0.113.0/24"
  ],
  "created_at": "2026-11-11T09:30:00Z",
  "created_by": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "env": "live",
  "expires_at": "2027-11-11T09:30:00Z",
  "hint": "EzXy",
  "last_used_at": null,
  "name": "MES feed",
  "previous_secret_expires_at": null,
  "rotated_at": null,
  "scopes": [
    "asset.read",
    "signal.query"
  ],
  "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Change an API key#

PATCH/v1/api-keys/{id}

Changes the name or the address list of a key that is active.

User sessionPermission api_key.updateRequires If-Match

Parameters

idpath · stringrequired
The ID of an API key of the tenant. Any other ID answers like a missing one.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

allowed_cidrsarray of strings
The address ranges the key may be used from; empty means any address (at most 20).
namestring
A name for the key, for example the system that uses it.

Returns

The updated key

Errors

not_foundversion_mismatchconflictunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed_cidrs": [
    "203.0.113.0/24"
  ],
  "name": "MES feed"
}'
Response200 OK
{
  "id": "key_01m71xxng7fzrvspnkgtw1t2km",
  "object": "api_key",
  "allowed_cidrs": [
    "203.0.113.0/24"
  ],
  "created_at": "2026-11-11T09:30:00Z",
  "created_by": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "env": "live",
  "expires_at": "2027-11-11T09:30:00Z",
  "hint": "EzXy",
  "last_used_at": null,
  "name": "MES feed",
  "previous_secret_expires_at": null,
  "rotated_at": null,
  "scopes": [
    "asset.read",
    "signal.query"
  ],
  "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Rotate an API key#

POST/v1/api-keys/{id}/rotate

Creates a new secret for the same key ID and returns the new key once; the old secret keeps working for the grace period. A second rotation during the grace period answers 409. Needs a user with a recent step-up authentication.

User sessionPermission api_key.rotateIdempotent with keyStep-up authentication

Parameters

idpath · stringrequired
The ID of an API key of the tenant. Any other ID answers like a missing one.
Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Body

gracestring
The grace period as an ISO 8601 duration, from one minute to 30 days; PT24H when omitted.

Returns

The key with its new secret

Errors

not_foundconflictstep_up_requiredpermission_deniedunavailable

curl -X POST https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym/rotate \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grace": "PT24H"
}'
Response200 OK
{
  "id": "key_01m71xxng7fzrvspnkgtw1t2km",
  "object": "api_key",
  "allowed_cidrs": [
    "203.0.113.0/24"
  ],
  "created_at": "2026-11-11T09:30:00Z",
  "created_by": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "env": "live",
  "expires_at": "2027-11-11T09:30:00Z",
  "hint": "EzXy",
  "last_used_at": null,
  "name": "MES feed",
  "previous_secret_expires_at": null,
  "rotated_at": null,
  "scopes": [
    "asset.read",
    "signal.query"
  ],
  "secret": "hive_live_01m71xxng7fzrvspnkgtw1t2km_Zk3p9Qd7LmW2xVb8Nc4TgYh6JrAe1UoSi5Fa0KwDqEzXy",
  "service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Service accounts

List the service accounts#

GET/v1/service-accounts

The service accounts of the tenant, newest first.

Permission service_account.list

Parameters

limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of service accounts

Errors

unavailable

curl https://api.hive.clerktree.com/v1/service-accounts?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
      "object": "service_account",
      "created_at": "2026-11-11T09:30:00Z",
      "description": "Feeds work orders from the MES of Musterwerk Esslingen.",
      "name": "integration-mes",
      "owner_user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
      "status": "active",
      "updated_at": "2026-11-11T09:30:00Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Create a service account#

POST/v1/service-accounts

Creates a service account with no permission at all. A name already used by a live account of the tenant answers 409.

User sessionPermission service_account.createIdempotent with key

Parameters

Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Body

descriptionstring
What the account is used for.
namestringrequired
The name of the account, unique among the live accounts of the tenant (compared without case).
owner_user_idstring
The user who is notified when a key expires; the caller when omitted.

Returns

The new service account

Errors

conflictlimit_exceededpermission_deniedunavailable

curl -X POST https://api.hive.clerktree.com/v1/service-accounts \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "integration-mes"
}'
Response201 Created
{
  "id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "object": "service_account",
  "created_at": "2026-11-11T09:30:00Z",
  "description": "Feeds work orders from the MES of Musterwerk Esslingen.",
  "name": "integration-mes",
  "owner_user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Delete a service account#

DELETE/v1/service-accounts/{id}

Revokes every key of the account, removes its grants and deletes the account. The name is free again.

User sessionPermission service_account.deleteRequires If-Match

Parameters

idpath · stringrequired
The ID of a service account of the tenant. Any other ID answers like a missing one.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Returns

The service account is deleted

Errors

not_foundunavailable

# ETAG: the ETag header of your last read of this resource
curl -X DELETE https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG"
Response204 No Content
No body

Get a service account#

GET/v1/service-accounts/{id}

One service account of the tenant.

Permission service_account.get

Parameters

idpath · stringrequired
The ID of a service account of the tenant. Any other ID answers like a missing one.

Returns

The service account

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "object": "service_account",
  "created_at": "2026-11-11T09:30:00Z",
  "description": "Feeds work orders from the MES of Musterwerk Esslingen.",
  "name": "integration-mes",
  "owner_user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Change a service account#

PATCH/v1/service-accounts/{id}

Changes the name, the description, the owner, or enables a disabled account.

User sessionPermission service_account.updateRequires If-Match

Parameters

idpath · stringrequired
The ID of a service account of the tenant. Any other ID answers like a missing one.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

descriptionstring
What the account is used for.
namestring
The name of the account, unique among the live accounts of the tenant (compared without case).
owner_user_idstring
The user who is notified when a key of the account expires.
statusenum
active enables a disabled account. One of active.

Returns

The updated service account

Errors

not_foundversion_mismatchconflictunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "integration-mes",
  "description": "Feeds work orders from the MES of Musterwerk Esslingen."
}'
Response200 OK
{
  "id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "object": "service_account",
  "created_at": "2026-11-11T09:30:00Z",
  "description": "Feeds work orders from the MES of Musterwerk Esslingen.",
  "name": "integration-mes",
  "owner_user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Disable a service account#

POST/v1/service-accounts/{id}/disable

All keys and tokens of the account stop working at once. Enable the account again with an update.

User sessionPermission service_account.disableIdempotent with key

Parameters

idpath · stringrequired
The ID of a service account of the tenant. Any other ID answers like a missing one.
Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Returns

The disabled service account

Errors

not_foundunavailable

curl -X POST https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym/disable \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)"
Response200 OK
{
  "id": "sva_01m71xxng7fzrvspnkgtw1t2kj",
  "object": "service_account",
  "created_at": "2026-11-11T09:30:00Z",
  "description": "Feeds work orders from the MES of Musterwerk Esslingen.",
  "name": "integration-mes",
  "owner_user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "status": "active",
  "updated_at": "2026-11-11T09:30:00Z",
  "version": 1
}

Assets

List the assets#

GET/v1/assets

The assets of the tenant that the caller may list, as a page. Filter by kind, parent_id, site_id, asset_type_id, lifecycle_state and key; q matches the start of a name or a key; under limits the list to a subtree. An asset outside the caller's scopes is left out and nothing counts it.

Permission asset.list

Parameters

limitquery · integer
The page size of a list, 1 to 500; the default is 50.
underquery · string
The root of a subtree: only this asset and the assets below it are listed. An ID of another tenant, or an unknown one, answers 404.
qquery · string
Assets whose name or key starts with this text, without regard to case.
include_deletedquery · boolean
true also lists deleted assets; it needs asset.delete.

Returns

A page of assets

Errors

not_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
      "object": "asset",
      "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
      "asset_type_version": 3,
      "build_year": 2019,
      "commissioned_on": "2019-09-02",
      "created_at": "2025-11-03T09:00:00Z",
      "deleted_at": null,
      "description_i18n": {
        "de": "5-Achs-Bearbeitungszentrum",
        "en": "5-axis machining centre"
      },
      "external_refs": [
        {
          "id": "10004711",
          "system": "sap-pm/equipment",
          "url": null
        }
      ],
      "key": "CNC-07",
      "kind": "machine",
      "lifecycle_changed_at": "2026-01-12T07:00:00Z",
      "lifecycle_state": "active",
      "manufacturer": "Kessler Werkzeugmaschinen AG",
      "model": "KM 500",
      "name": "CNC-07 5-axis machining centre",
      "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
      "path_keys": [
        "Musterwerk Esslingen",
        "Halle 1",
        "Line 2",
        "CNC-07"
      ],
      "properties": {
        "rated_spindle_speed": {
          "unit": "1/min",
          "value": 12000
        }
      },
      "serial_number": "KM500-190412",
      "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
      "site_profile": {
        "address": null,
        "country": "DE",
        "time_zone": "Europe/Berlin"
      },
      "sort_order": 0,
      "updated_at": "2026-01-12T07:00:00Z",
      "variant": null,
      "version": 5
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Create an asset#

POST/v1/assets

Creates a site, area, line, work unit, machine or component. The parent must be of an allowed kind and not decommissioned, the tree at most 8 levels deep and the key unused. A site needs its time zone and country. The caller needs asset.create on the parent (for a site: on the tenant).

Permission asset.createIdempotent with key

Parameters

Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Body

asset_type_idstring
The asset type, or null.
build_yearinteger
The year the equipment was built.
commissioned_onstring (date)
The date the equipment was first put into service.
description_i18nobject
A description per language tag (BCP 47), for example de and en.
external_refsarray of objects
keystring
The human key, 1 to 64 characters from A-Z a-z 0-9 . _ / space and hyphen, unique in the tenant without regard to case among assets that are not deleted.
kindenumrequired
The kind of node in the hierarchy: site, area, line, work_unit, machine or component. It cannot be changed. One of site, area, line, work_unit, machine, component.
manufacturerstring
The manufacturer.
modelstring
The model.
namestringrequired
The display name.
parent_idstring
The parent asset. Required for every kind except a site, which has none.
propertiesobject
Free properties of the asset, at most 16 KiB. When the asset has a type they validate against its property schema.
serial_numberstring
The serial number of the manufacturer.
site_profileobject
Required for a site: the time zone and country, with an optional address. Refused for every other kind.
sort_orderinteger
The position among the siblings; ties break by name.
variantstring
The variant.

Returns

The new asset

Errors

conflictlimit_exceedednot_foundpermission_deniedprecondition_failedunavailable

curl -X POST https://api.hive.clerktree.com/v1/assets \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "machine",
  "name": "CNC-07 5-axis machining centre"
}'
Response201 Created
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

Delete an asset#

DELETE/v1/assets/{id}

Soft delete: the asset disappears from every normal read and can be restored until the retention job purges it. Only a planned or decommissioned asset can be deleted; one with children needs cascade=true. A subtree of more than 2,000 assets is refused with 400 (delete it in parts): asynchronous operations are started by a POST.

Permission asset.deleteRequires If-Match

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
cascadequery · boolean
true also deletes every asset below this one; without it an asset with children is refused.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Returns

The asset is deleted

Errors

conflictinvalid_requestnot_foundpermission_deniedprecondition_failedunavailableversion_mismatch

# ETAG: the ETag header of your last read of this resource
curl -X DELETE https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG"
Response204 No Content
No body

Get an asset#

GET/v1/assets/{id}

One asset with its place in the tree. An asset of another tenant, or an unknown ID, answers 404 not_found.

Permission asset.read

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.

Returns

The asset

Errors

not_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

Change an asset#

PATCH/v1/assets/{id}

Changes name, key, description, type, manufacturer, model, variant, serial number, build year, commissioning date, properties, sort order or the site profile. It needs If-Match with the current version. The kind and the parent cannot be changed here.

Permission asset.updateRequires If-Match

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

asset_type_idstring
The asset type, or null.
build_yearinteger
The year the equipment was built.
commissioned_onstring (date)
The date the equipment was first put into service.
description_i18nobject
A description per language tag (BCP 47), for example de and en.
keystring
The human key, 1 to 64 characters from A-Z a-z 0-9 . _ / space and hyphen, unique in the tenant without regard to case among assets that are not deleted.
manufacturerstring
The manufacturer.
modelstring
The model.
namestring
The display name.
propertiesobject
Free properties of the asset, at most 16 KiB. When the asset has a type they validate against its property schema.
serial_numberstring
The serial number of the manufacturer.
site_profileobject
Changes the site profile of a site; refused for every other kind. Changing the time zone emits asset.updated and consumers react.
sort_orderinteger
The position among the siblings; ties break by name.
variantstring
The variant.

Returns

The changed asset

Errors

conflictnot_foundpermission_deniedprecondition_failedprecondition_requiredunavailableversion_mismatch

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CNC-07 5-axis machining centre",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym"
}'
Response200 OK
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

List the ancestors of an asset#

GET/v1/assets/{id}/ancestors

The path to the site: the parent first and the site last. The list is never paged.

Permission asset.list

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.

Returns

The ancestors

Errors

not_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/ancestors \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
      "object": "asset",
      "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
      "asset_type_version": 3,
      "build_year": 2019,
      "commissioned_on": "2019-09-02",
      "created_at": "2025-11-03T09:00:00Z",
      "deleted_at": null,
      "description_i18n": {
        "de": "5-Achs-Bearbeitungszentrum",
        "en": "5-axis machining centre"
      },
      "external_refs": [
        {
          "id": "10004711",
          "system": "sap-pm/equipment",
          "url": null
        }
      ],
      "key": "CNC-07",
      "kind": "machine",
      "lifecycle_changed_at": "2026-01-12T07:00:00Z",
      "lifecycle_state": "active",
      "manufacturer": "Kessler Werkzeugmaschinen AG",
      "model": "KM 500",
      "name": "CNC-07 5-axis machining centre",
      "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
      "path_keys": [
        "Musterwerk Esslingen",
        "Halle 1",
        "Line 2",
        "CNC-07"
      ],
      "properties": {
        "rated_spindle_speed": {
          "unit": "1/min",
          "value": 12000
        }
      },
      "serial_number": "KM500-190412",
      "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
      "site_profile": {
        "address": null,
        "country": "DE",
        "time_zone": "Europe/Berlin"
      },
      "sort_order": 0,
      "updated_at": "2026-01-12T07:00:00Z",
      "variant": null,
      "version": 5
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List the children of an asset#

GET/v1/assets/{id}/children

The direct children, ordered by sort order.

Permission asset.list

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of assets

Errors

not_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/children?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
      "object": "asset",
      "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
      "asset_type_version": 3,
      "build_year": 2019,
      "commissioned_on": "2019-09-02",
      "created_at": "2025-11-03T09:00:00Z",
      "deleted_at": null,
      "description_i18n": {
        "de": "5-Achs-Bearbeitungszentrum",
        "en": "5-axis machining centre"
      },
      "external_refs": [
        {
          "id": "10004711",
          "system": "sap-pm/equipment",
          "url": null
        }
      ],
      "key": "CNC-07",
      "kind": "machine",
      "lifecycle_changed_at": "2026-01-12T07:00:00Z",
      "lifecycle_state": "active",
      "manufacturer": "Kessler Werkzeugmaschinen AG",
      "model": "KM 500",
      "name": "CNC-07 5-axis machining centre",
      "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
      "path_keys": [
        "Musterwerk Esslingen",
        "Halle 1",
        "Line 2",
        "CNC-07"
      ],
      "properties": {
        "rated_spindle_speed": {
          "unit": "1/min",
          "value": 12000
        }
      },
      "serial_number": "KM500-190412",
      "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
      "site_profile": {
        "address": null,
        "country": "DE",
        "time_zone": "Europe/Berlin"
      },
      "sort_order": 0,
      "updated_at": "2026-01-12T07:00:00Z",
      "variant": null,
      "version": 5
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

List the descendants of an asset#

GET/v1/assets/{id}/descendants

Every asset below this one, to the depth asked for, ordered by sort order. Filter by kind.

Permission asset.list

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
limitquery · integer
The page size of a list, 1 to 500; the default is 50.
depthquery · integer
How many levels below the asset to list, 1 to 7; all of them when absent.

Returns

A page of assets

Errors

not_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/descendants?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
      "object": "asset",
      "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
      "asset_type_version": 3,
      "build_year": 2019,
      "commissioned_on": "2019-09-02",
      "created_at": "2025-11-03T09:00:00Z",
      "deleted_at": null,
      "description_i18n": {
        "de": "5-Achs-Bearbeitungszentrum",
        "en": "5-axis machining centre"
      },
      "external_refs": [
        {
          "id": "10004711",
          "system": "sap-pm/equipment",
          "url": null
        }
      ],
      "key": "CNC-07",
      "kind": "machine",
      "lifecycle_changed_at": "2026-01-12T07:00:00Z",
      "lifecycle_state": "active",
      "manufacturer": "Kessler Werkzeugmaschinen AG",
      "model": "KM 500",
      "name": "CNC-07 5-axis machining centre",
      "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
      "path_keys": [
        "Musterwerk Esslingen",
        "Halle 1",
        "Line 2",
        "CNC-07"
      ],
      "properties": {
        "rated_spindle_speed": {
          "unit": "1/min",
          "value": 12000
        }
      },
      "serial_number": "KM500-190412",
      "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
      "site_profile": {
        "address": null,
        "country": "DE",
        "time_zone": "Europe/Berlin"
      },
      "sort_order": 0,
      "updated_at": "2026-01-12T07:00:00Z",
      "variant": null,
      "version": 5
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Change the lifecycle of an asset#

POST/v1/assets/{id}/lifecycle

Moves the asset along planned, commissioning, active, standby and decommissioned. Decommissioning also decommissions everything below it. It is metadata and never acts on a machine.

Permission asset.updateIdempotent with keyRequires If-Match

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

effective_atstring (date-time)
When the change took effect, possibly in the past; it only labels lifecycle_changed_at. Null means now.
reasonstring
Why, in a sentence; it is not logged.
toenumrequired
The state to go to. One of planned, commissioning, active, standby, decommissioned.

Returns

The asset in its new state

Errors

not_foundpermission_deniedprecondition_failedunavailableversion_mismatch

# ETAG: the ETag header of your last read of this resource
curl -X POST https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/lifecycle \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "standby"
}'
Response200 OK
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

Move an asset#

POST/v1/assets/{id}/move

Moves an asset with its whole subtree under another parent in one step. It needs If-Match with the current version. The caller needs asset.move on the old and on the new parent. A new parent inside the subtree answers 422 move_cycle. Moving more than 2,000 assets answers 202 with an operation.

Permission asset.moveIdempotent with keyRequires If-MatchAsynchronous

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

new_parent_idstringrequired
The new parent asset, in the same tenant.
sort_orderinteger
The position among the new siblings; the current one is kept when absent.

Returns

The moved asset

Errors

conflictnot_foundpermission_deniedprecondition_failedprecondition_requiredunavailableversion_mismatch

# ETAG: the ETag header of your last read of this resource
curl -X POST https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/move \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "new_parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc"
}'
Response200 OK
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

Restore a deleted asset#

POST/v1/assets/{id}/restore

Brings a deleted asset and the assets that were deleted with it back. It fails with 409 when its key was taken meanwhile or its parent is deleted.

Permission asset.deleteIdempotent with key

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
Idempotency-Keyheader · string
Client-chosen key making a create or action safe to retry.

Returns

The restored asset

Errors

conflictnot_foundpermission_deniedunavailable

curl -X POST https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/restore \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Idempotency-Key: $(uuidgen)"
Response200 OK
{
  "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "object": "asset",
  "asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym",
  "asset_type_version": 3,
  "build_year": 2019,
  "commissioned_on": "2019-09-02",
  "created_at": "2025-11-03T09:00:00Z",
  "deleted_at": null,
  "description_i18n": {
    "de": "5-Achs-Bearbeitungszentrum",
    "en": "5-axis machining centre"
  },
  "external_refs": [
    {
      "id": "10004711",
      "system": "sap-pm/equipment",
      "url": null
    }
  ],
  "key": "CNC-07",
  "kind": "machine",
  "lifecycle_changed_at": "2026-01-12T07:00:00Z",
  "lifecycle_state": "active",
  "manufacturer": "Kessler Werkzeugmaschinen AG",
  "model": "KM 500",
  "name": "CNC-07 5-axis machining centre",
  "parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc",
  "path_keys": [
    "Musterwerk Esslingen",
    "Halle 1",
    "Line 2",
    "CNC-07"
  ],
  "properties": {
    "rated_spindle_speed": {
      "unit": "1/min",
      "value": 12000
    }
  },
  "serial_number": "KM500-190412",
  "site_id": "ast_01m71xxn9ze26b4pq3dnxee9ms",
  "site_profile": {
    "address": null,
    "country": "DE",
    "time_zone": "Europe/Berlin"
  },
  "sort_order": 0,
  "updated_at": "2026-01-12T07:00:00Z",
  "variant": null,
  "version": 5
}

Read the shift at an instant#

GET/v1/assets/{id}/shift-at

The shift that runs at an instant for a site: a shift belongs to the local date on which it starts, windows are half-open and an instant on a boundary belongs to the later shift. With no shift at that instant shift_key and the window are null. The instant needs a numeric offset or Z; one without an offset answers 400 with timestamp_requires_offset.

Permission shift.read

Parameters

idpath · stringrequired
The ID of a site asset of the tenant. Any other ID answers like a missing one.
atquery · string (date-time)required
The instant, RFC 3339 with Z or a numeric offset.

Returns

The shift window, or nulls

Errors

invalid_requestnot_foundunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-at?at=2026-11-01T08:00:00Z \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "shift_window",
  "end_at": "2026-11-10T13:00:00Z",
  "shift_key": "A",
  "shift_on": "2026-11-10",
  "site_id": "ast_01jc8z3k5me9rt7q2v4x6b0dnh",
  "start_at": "2026-11-10T05:00:00Z",
  "time_zone": "Europe/Berlin"
}

List the shift windows of a site#

GET/v1/assets/{id}/shift-windows

The shifts of a site that start on a local date from from_on to to_on, both inclusive, at most 62 days, ordered by start. The duration of a window is its real elapsed time: a night shift is 9 or 7 hours on a transition night. The list is never paged.

Permission shift.list

Parameters

idpath · stringrequired
The ID of a site asset of the tenant. Any other ID answers like a missing one.
from_onquery · string (date)required
The first local date, inclusive.
to_onquery · string (date)required
The last local date, inclusive. At most 62 days after from_on.

Returns

The shift windows

Errors

invalid_requestnot_foundunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-windows?from_on=2026-11-01&to_on=2026-11-01 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "object": "shift_window",
      "end_at": "2026-11-10T13:00:00Z",
      "shift_key": "A",
      "shift_on": "2026-11-10",
      "site_id": "ast_01jc8z3k5me9rt7q2v4x6b0dnh",
      "start_at": "2026-11-10T05:00:00Z",
      "time_zone": "Europe/Berlin"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Read a nested tree#

GET/v1/assets/{id}/tree

The asset and its descendants as nested JSON, siblings ordered by sort order and name. At most 2,000 nodes; a larger tree answers 400, read it with descendants instead.

Permission asset.list

Parameters

idpath · stringrequired
The ID of an asset of the tenant. Any other ID answers like a missing one.
depthquery · integer
How many levels below the asset to nest, 1 to 7; the default is 3.

Returns

The tree

Errors

invalid_requestnot_foundpermission_deniedunavailable

curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/tree \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "asset_tree",
  "depth": 3,
  "node_count": 11,
  "root": {
    "id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
    "object": "asset_tree_node",
    "children": [
      {}
    ],
    "key": "CNC-07",
    "kind": "machine",
    "lifecycle_state": "active",
    "name": "CNC-07 5-axis machining centre",
    "sort_order": 0
  }
}

Clock statuses

List the clock statuses#

GET/v1/clock-statuses

The clock status of the gateways and connections of the tenant: the state, since when, and the measured offset. Filter by state and source_kind. A gateway status is gateway minus cloud time; a connection status is the median of the gateway time minus the source time of its live samples.

Permission clock_status.read

Parameters

limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of clock statuses

Errors

unavailable

curl https://api.hive.clerktree.com/v1/clock-statuses?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "cnx_01jc8z3k5me9rt7q2v4x6b0dnh",
      "object": "clock_status",
      "created_at": "2026-11-01T08:00:00Z",
      "drift_ppm": null,
      "gateway_id": "gwy_01jc8z1abcdef0123456789xyz",
      "measured_at": "2026-11-10T05:12:00Z",
      "offset_ms": -41200,
      "rtt_ms": null,
      "sample_count": 300,
      "source_kind": "connection",
      "state": "skewed",
      "state_since": "2026-11-10T04:55:00Z",
      "step": null,
      "step_at": null,
      "stratum": null,
      "sync_source": null,
      "updated_at": "2026-11-10T05:12:00Z",
      "version": 14
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Get a clock status#

GET/v1/clock-statuses/{id}

The clock status of one gateway or connection of the tenant. The ID is the gwy or cnx ID. An ID of another tenant, or an unknown one, answers 404 not_found.

Permission clock_status.read

Parameters

idpath · stringrequired
The ID of a gateway or connection of the tenant (gwy or cnx). Any other ID answers like a missing one.

Returns

The clock status

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/clock-statuses/string \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "cnx_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "clock_status",
  "created_at": "2026-11-01T08:00:00Z",
  "drift_ppm": null,
  "gateway_id": "gwy_01jc8z1abcdef0123456789xyz",
  "measured_at": "2026-11-10T05:12:00Z",
  "offset_ms": -41200,
  "rtt_ms": null,
  "sample_count": 300,
  "source_kind": "connection",
  "state": "skewed",
  "state_since": "2026-11-10T04:55:00Z",
  "step": null,
  "step_at": null,
  "stratum": null,
  "sync_source": null,
  "updated_at": "2026-11-10T05:12:00Z",
  "version": 14
}

List the substituted timestamps of a connection#

GET/v1/clock-statuses/{id}/exceptions

The bounded log of timestamps that ingest replaced by the gateway time (the first 100 per connection per hour): the value as received, the value stored, the verdict and the signal. A gateway has no exceptions of its own: its list is empty.

Permission time_exception.read

Parameters

idpath · stringrequired
The ID of a gateway or connection of the tenant (gwy or cnx). Any other ID answers like a missing one.
limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of exceptions

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/clock-statuses/string/exceptions?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "object": "time_exception",
      "signal_id": "sig_01jc8z3k5me9rt7q2v4x6b0dnh",
      "t_ingest": "2026-11-10T05:12:03.610Z",
      "t_original_raw": "1601-01-01T00:00:00Z",
      "t_stored": "2026-11-10T05:12:03.482Z",
      "verdict": "epoch_sentinel"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Current user

List the tenants of the caller#

GET/v1/me/tenants

The tenants the calling user has an active membership of, for choosing the Hive-Tenant of later requests. A user credential only; no tenant is selected. Served by the global plane.

User sessionPermission me.read

Returns

The caller's tenants

Errors

principal_not_allowedunavailable

curl https://api.hive.clerktree.com/v1/me/tenants \
  -H "Authorization: Bearer $HIVE_USER_TOKEN" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "display_name": "Musterwerk Esslingen",
      "id": "ten_01jc8z3k5me9rt7q2v4x6b0dnh",
      "object": "me_tenant",
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Integrations

Receive a secret scanning report#

POST/v1/integrations/secret-scanning/github

The endpoint for the secret scanning partner programme of GitHub. The signature of the request, checked against the published public keys of the partner, is the authentication; a request without a valid signature answers 401. A reported token that is a live API key is revoked, marked compromised and reported to the security admins. The format of the answer is the one of the partner programme and is to be verified against its current documentation.

No authentication

Returns

The verdict for each token

Errors

unauthenticatedunavailable

curl -X POST https://api.hive.clerktree.com/v1/integrations/secret-scanning/github \
  -H "Hive-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "source": "content",
    "token": "hive_live_01m71xxng7fzrvspnkgtw1t2km_NotARealSecretNotARealSecretNotARealSecrXXXXXX",
    "type": "hive_api_key",
    "url": "https://github.com/example/musterwerk-integration/blob/main/.env"
  }
]'
Response200 OK
[
  {
    "label": "false_positive",
    "token_raw": "hive_live_01m71xxng7fzrvspnkgtw1t2km_NotARealSecretNotARealSecretNotARealSecrXXXXXX",
    "token_type": "hive_api_key"
  }
]

Memberships

List the memberships of the current tenant#

GET/v1/memberships

Who belongs to the tenant, with status and source. Only this tenant's memberships are visible; nothing reveals another tenant of the same user.

Permission membership.list

Parameters

limitquery · integer
The page size of a list, 1 to 500; the default is 50.

Returns

A page of memberships

Errors

unavailable

curl https://api.hive.clerktree.com/v1/memberships?limit=20 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "object": "membership",
      "created_at": "2026-09-01T08:00:00Z",
      "source": "sso",
      "status": "active",
      "updated_at": "2026-11-01T09:30:00Z",
      "user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
      "version": 2
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": null,
  "total_count_is_lower_bound": null
}

Suspend or reactivate a membership#

PATCH/v1/memberships/{user_id}

Sets the status of one membership of the current tenant to suspended or active. The directory is changed first and the cells follow within seconds.

Permission membership.updateRequires If-Match

Parameters

user_idpath · stringrequired
The user of the membership.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

statusenumrequired
The new status. A member can be suspended or made active again; removal of a user goes through user management. One of active, suspended.

Returns

The updated membership

Errors

not_foundversion_mismatchconflictunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/memberships/usr_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "suspended"
}'
Response200 OK
{
  "object": "membership",
  "created_at": "2026-09-01T08:00:00Z",
  "source": "sso",
  "status": "active",
  "updated_at": "2026-11-01T09:30:00Z",
  "user_id": "usr_01m71xxng7fzrvspnkgtw1t2kg",
  "version": 2
}

Sites

List the site profiles#

GET/v1/sites

The site profiles of the current tenant: time zone, country and address of each site.

Permission site.list

Returns

The site profiles

Errors

unavailable

curl https://api.hive.clerktree.com/v1/sites \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "object": "site",
      "address": {
        "city": "Esslingen am Neckar",
        "postal_code": "73730",
        "street": "Plochinger Strasse 12"
      },
      "asset_id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
      "country_code": "DE",
      "created_at": "2026-09-01T08:00:00Z",
      "time_zone": "Europe/Berlin",
      "updated_at": "2026-11-01T09:30:00Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create or update a site profile#

PATCH/v1/sites/{id}

Sets the time zone, country or address of a site. The site must be an asset of kind site; a time zone that is not in the IANA database is refused with a 400.

Permission site.updateRequires If-Match

Parameters

idpath · stringrequired
The asset of kind site.
If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

addressobject
The postal address; free form. Null clears it.
country_codestring
The ISO 3166 alpha-2 country code.
time_zonestring
The IANA time zone, for example Europe/Berlin. A name that is not in the time zone database is refused.

Returns

The site profile

Errors

not_foundversion_mismatchunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/sites/ast_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {
    "city": "Esslingen am Neckar",
    "postal_code": "73730",
    "street": "Plochinger Strasse 12"
  },
  "country_code": "DE",
  "time_zone": "Europe/Berlin"
}'
Response200 OK
{
  "object": "site",
  "address": {
    "city": "Esslingen am Neckar",
    "postal_code": "73730",
    "street": "Plochinger Strasse 12"
  },
  "asset_id": "ast_01m71xxng7fzrvspnkgtw1t2kg",
  "country_code": "DE",
  "created_at": "2026-09-01T08:00:00Z",
  "time_zone": "Europe/Berlin",
  "updated_at": "2026-11-01T09:30:00Z",
  "version": 1
}

Tenants

Retrieve the current tenant#

GET/v1/tenants/current

The tenant the request acts in: handle, display name, state, language, cell, region, contract and API version.

Permission tenant.read

Returns

The tenant

Errors

unavailable

curl https://api.hive.clerktree.com/v1/tenants/current \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "ten_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "tenant",
  "api_version": "2026-11-01",
  "cell": "eu-central-1a",
  "contract_id": "ctr_01jc8z3k5me9rt7q2v4x6b0dnj",
  "created_at": "2026-09-01T08:00:00Z",
  "default_language": "de",
  "display_name": "Musterwerk Esslingen",
  "handle": "musterwerk-esslingen",
  "region": "eu-central-1",
  "state": "active",
  "updated_at": "2026-11-01T09:30:00Z",
  "version": 3
}

Update the current tenant#

PATCH/v1/tenants/current

Changes the display name or the default language. The handle, the ID and the state cannot be changed; an unknown field is a 400. Send the version in If-Match.

Permission tenant.updateRequires If-Match

Parameters

If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

default_languageenum
The new default language. One of de, en.
display_namestring
The new display name.

Returns

The updated tenant

Errors

not_foundversion_mismatchunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/tenants/current \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "default_language": "en",
  "display_name": "Musterwerk Esslingen"
}'
Response200 OK
{
  "id": "ten_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "tenant",
  "api_version": "2026-11-01",
  "cell": "eu-central-1a",
  "contract_id": "ctr_01jc8z3k5me9rt7q2v4x6b0dnj",
  "created_at": "2026-09-01T08:00:00Z",
  "default_language": "de",
  "display_name": "Musterwerk Esslingen",
  "handle": "musterwerk-esslingen",
  "region": "eu-central-1",
  "state": "active",
  "updated_at": "2026-11-01T09:30:00Z",
  "version": 3
}

Retrieve a tenant by ID#

GET/v1/tenants/{id}

Only the tenant of the request can be read here: the ID is compared with the context and nothing else, so any other ID answers 404 exactly as a missing one does.

Permission tenant.read

Parameters

idpath · stringrequired
A tenant ID. Only the tenant of the request is readable: any other ID answers like a missing one.

Returns

The tenant

Errors

not_foundunavailable

curl https://api.hive.clerktree.com/v1/tenants/ten_01m71xxqhkf9avn6dq2sfgzgym \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "ten_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "tenant",
  "api_version": "2026-11-01",
  "cell": "eu-central-1a",
  "contract_id": "ctr_01jc8z3k5me9rt7q2v4x6b0dnj",
  "created_at": "2026-09-01T08:00:00Z",
  "default_language": "de",
  "display_name": "Musterwerk Esslingen",
  "handle": "musterwerk-esslingen",
  "region": "eu-central-1",
  "state": "active",
  "updated_at": "2026-11-01T09:30:00Z",
  "version": 3
}

Time

Read the cloud time#

GET/v1/time

The time of the cloud as the API sees it, in UTC with Z, the release of the time zone data in use (tzdata_version) and the default time zone of a site. Clients use it to judge their own clock. It touches no tenant data.

Permission time.read

Returns

The cloud time

Errors

unavailable

curl https://api.hive.clerktree.com/v1/time \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "server_time",
  "now": "2026-11-10T05:12:03.482391Z",
  "time_zone_default": "Europe/Berlin",
  "tzdata_version": "2025c"
}

Units

List the quantity kinds of the registry#

GET/v1/quantity-kinds

The kinds that say which units may be converted into each other, with the units each lists, its canonical unit and its default number of decimals.

Permission unit.read

Returns

The quantity kinds

Errors

unavailable

curl https://api.hive.clerktree.com/v1/quantity-kinds \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "pressure",
      "object": "quantity_kind",
      "canonical_unit": "bar",
      "created_at": "2026-11-01T00:00:00Z",
      "default_decimals": 1,
      "is_deprecated": false,
      "is_reference_conditions_required": false,
      "name_i18n": {
        "de": "Druck",
        "en": "Pressure"
      },
      "registry_version": "2026.11.1+5dbe9dd356f6",
      "units": [
        "bar",
        "mbar",
        "Pa",
        "kPa",
        "MPa",
        "[psi]"
      ],
      "updated_at": "2026-11-01T00:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve the unit preferences of the tenant#

GET/v1/unit-preferences

The display units of the current tenant. The document exists from the first request: a tenant that never chose gets the defaults (no display units, colloquial style) at version 1.

Permission unit_preference.read

Returns

The unit preferences

Errors

unavailable

curl https://api.hive.clerktree.com/v1/unit-preferences \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "id": "unp_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "unit_preferences",
  "created_at": "2026-11-01T09:00:00Z",
  "display_units": {
    "pressure": "bar"
  },
  "rotational_speed_style": "colloquial",
  "updated_at": "2026-11-10T09:30:00Z",
  "version": 3
}

Change the unit preferences of the tenant#

PATCH/v1/unit-preferences

Sets the display units and the rotational speed style of the tenant. A member that is sent replaces that member as a whole: display_units is the complete map, a kind that is left out goes back to its canonical unit. Send the version in If-Match (required). A key that is not a quantity kind, or a unit that is not one of its kind, is refused with 400 and the reason unit_not_in_kind; nothing is stored then.

Permission unit_preference.updateRequires If-Match

Parameters

If-Matchheader · string
The version of the record the client read, as an ETag; a mismatch answers 412 version_mismatch.

Body

display_unitsobject
The unit per quantity kind. Every key is a kind slug and every value a unit of that kind.
rotational_speed_styleenum
The German label of 1/min: colloquial or din. One of colloquial, din.

Returns

The changed unit preferences

Errors

version_mismatchprecondition_requiredunavailable

# ETAG: the ETag header of your last read of this resource
curl -X PATCH https://api.hive.clerktree.com/v1/unit-preferences \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{
  "display_units": {
    "pressure": "bar",
    "temperature": "Cel"
  },
  "rotational_speed_style": "din"
}'
Response200 OK
{
  "id": "unp_01jc8z3k5me9rt7q2v4x6b0dnh",
  "object": "unit_preferences",
  "created_at": "2026-11-01T09:00:00Z",
  "display_units": {
    "pressure": "bar"
  },
  "rotational_speed_style": "colloquial",
  "updated_at": "2026-11-10T09:30:00Z",
  "version": 3
}

List the units of the registry#

GET/v1/units

The units HIVE accepts, with the quantity kinds that list each and the labels in German and English. The registry is global reference data and the same for every tenant. kind narrows the list to one quantity kind. The list is never paged: there are fewer than a hundred units.

Permission unit.read

Parameters

kindquery · string
Only the units of this quantity kind (a slug of GET /v1/quantity-kinds).

Returns

The units

Errors

unavailable

curl https://api.hive.clerktree.com/v1/units \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01"
Response200 OK
{
  "object": "list",
  "data": [
    {
      "id": "bar",
      "object": "unit",
      "affine": false,
      "code": "bar",
      "created_at": "2026-11-01T00:00:00Z",
      "is_deprecated": false,
      "kinds": [
        "pressure"
      ],
      "label_i18n": {
        "de": "bar",
        "en": "bar"
      },
      "registry_version": "2026.11.1+5dbe9dd356f6",
      "updated_at": "2026-11-01T00:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Convert a value between two units#

POST/v1/units/convert

Converts one value exactly (relative error at most 1e-12). Affine units (Cel, [degF]) use their offset. A conversion between units that share no kind, or whose named kinds differ, answers 422 precondition_failed with unit_incompatible and converts nothing. Units are matched exactly and case-sensitively; an alias such as rpm or Bar is refused with 400 and never corrected.

Permission unit.read

Body

fromstringrequired
The unit of value.
from_kindstring
The quantity kind of the value. When only one kind is named it applies to both sides.
tostringrequired
The unit to convert to.
to_kindstring
The quantity kind of the result.
valuenumberrequired
The value to convert. A finite number: NaN and infinity are refused.

Returns

The converted value

Errors

precondition_failedunavailable

curl -X POST https://api.hive.clerktree.com/v1/units/convert \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "bar",
  "to": "[psi]",
  "value": 5.4
}'
Response200 OK
{
  "object": "conversion",
  "factor_used": 14.50377377302092,
  "offset_used": 0,
  "unit": "[psi]",
  "value": 78.32037837431298
}

Format a quantity for a person#

POST/v1/units/format

Writes a value and a unit the way a person of the locale reads it: decimal comma and dotted grouping in German, U+00A0 between number and unit, the registry's own unit labels. Only the text is rounded. A locale that is not supported falls back to its language, then to en, and the response names the locale used.

Permission unit.read

Body

count_noun_i18nobject
The noun shown after a count (unit 1), for example Teile and parts. Without it a count has no unit label.
kindstring
The quantity kind of the value; it selects the default decimals and the suffix of its units (m³/h (Normal) for compressed air).
localestring
A BCP 47 tag. de and en are supported; an unsupported tag falls back to its language, then to en, and the response says which locale was used.
precisioninteger
The number of decimals, 0 to 10. Without it the display_precision of the signal or the default of the kind is used; trailing zeros are not shown.
styleenum
The German label of 1/min: colloquial (U/min, the default) or din (min⁻¹). It has no effect on other units or on English. One of colloquial, din.
unitstringrequired
The unit of value, a registered code.
valuenumberrequired
The value to format. A finite number.

Returns

The formatted quantity

Errors

unavailable

curl -X POST https://api.hive.clerktree.com/v1/units/format \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Hive-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
  "unit": "mm/s",
  "value": 7.8
}'
Response200 OK
{
  "object": "formatted_quantity",
  "locale": "de",
  "text": "7,8 mm/s",
  "unit_label": "mm/s",
  "value_text": "7,8"
}