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
curl https://api.hive.clerktree.com/v1/health \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/health", {
headers: {
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/health",
headers={
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
Parameters
versionquery · string- A released dated version. Absent means the latest released version.
Returns
The document, without internal operations, tenant data or secrets
Errors
curl https://api.hive.clerktree.com/v1/asyncapi.json \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/asyncapi.json", {
headers: {
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/asyncapi.json",
headers={
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
Parameters
versionquery · string- A released dated version. Absent means the latest released version.
Returns
The document, without internal operations, tenant data or secrets
Errors
curl https://api.hive.clerktree.com/v1/openapi.json \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/openapi.json", {
headers: {
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/openapi.json",
headers={
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
api_version.readReturns
The versions
Errors
curl https://api.hive.clerktree.com/v1/api-versions \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/api-versions", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/api-versions",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
api_version.updateIdempotent with keyPeople onlyParameters
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
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"
}'const response = await fetch("https://api.hive.clerktree.com/v1/api-versions/pin", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"version": "2027-04-01"
}),
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/api-versions/pin",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"version": "2027-04-01"
},
)
data = response.json(){
"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.
api_version.readParameters
versionpath · stringrequired- A dated API version
Returns
The version
Errors
curl https://api.hive.clerktree.com/v1/api-versions/string \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/api-versions/string", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/api-versions/string",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
api_key.listParameters
limitquery · integer- The page size of a list, 1 to 500; the default is 50.
Returns
A page of API keys
Errors
curl https://api.hive.clerktree.com/v1/api-keys?limit=20 \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/api-keys?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/api-keys?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
api_key.createIdempotent with keyStep-up authenticationParameters
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"
}'const response = await fetch("https://api.hive.clerktree.com/v1/api-keys", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"env": "live",
"name": "MES feed",
"scopes": [
"signal.query",
"asset.read",
"work_order.*"
],
"service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj"
}),
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/api-keys",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"env": "live",
"name": "MES feed",
"scopes": [
"signal.query",
"asset.read",
"work_order.*"
],
"service_account_id": "sva_01m71xxng7fzrvspnkgtw1t2kj"
},
)
data = response.json(){
"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.
api_key.revokeRequires If-MatchParameters
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
# 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"// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym", {
method: "DELETE",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"If-Match": etag
},
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.delete(
"https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
)
data = response.json()No bodyGet an API key#
GET/v1/api-keys/{id}
One API key of the tenant, with its hint and metadata and without its secret.
api_key.getParameters
idpath · stringrequired- The ID of an API key of the tenant. Any other ID answers like a missing one.
Returns
The key
Errors
curl https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
api_key.updateRequires If-MatchParameters
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
# 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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"allowed_cidrs": [
"203.0.113.0/24"
],
"name": "MES feed"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"allowed_cidrs": [
"203.0.113.0/24"
],
"name": "MES feed"
},
)
data = response.json(){
"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.
api_key.rotateIdempotent with keyStep-up authenticationParameters
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"
}'const response = await fetch("https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym/rotate", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"grace": "PT24H"
}),
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/api-keys/key_01m71xxqhkf9avn6dq2sfgzgym/rotate",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"grace": "PT24H"
},
)
data = response.json(){
"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.
service_account.listParameters
limitquery · integer- The page size of a list, 1 to 500; the default is 50.
Returns
A page of service accounts
Errors
curl https://api.hive.clerktree.com/v1/service-accounts?limit=20 \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/service-accounts?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
service_account.createIdempotent with keyParameters
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
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"
}'const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "integration-mes"
}),
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/service-accounts",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"name": "integration-mes"
},
)
data = response.json(){
"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.
service_account.deleteRequires If-MatchParameters
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
# 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"// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym", {
method: "DELETE",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"If-Match": etag
},
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.delete(
"https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
)
data = response.json()No bodyGet a service account#
GET/v1/service-accounts/{id}
One service account of the tenant.
service_account.getParameters
idpath · stringrequired- The ID of a service account of the tenant. Any other ID answers like a missing one.
Returns
The service account
Errors
curl https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
service_account.updateRequires If-MatchParameters
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
# 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."
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "integration-mes",
"description": "Feeds work orders from the MES of Musterwerk Esslingen."
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"name": "integration-mes",
"description": "Feeds work orders from the MES of Musterwerk Esslingen."
},
)
data = response.json(){
"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.
service_account.disableIdempotent with keyParameters
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
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)"const response = await fetch("https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym/disable", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID()
},
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/service-accounts/sva_01m71xxqhkf9avn6dq2sfgzgym/disable",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
)
data = response.json(){
"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.
asset.listParameters
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
curl https://api.hive.clerktree.com/v1/assets?limit=20 \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/assets?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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).
asset.createIdempotent with keyParameters
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 objectskeystring- 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"
}'const response = await fetch("https://api.hive.clerktree.com/v1/assets", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"kind": "machine",
"name": "CNC-07 5-axis machining centre"
}),
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/assets",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"kind": "machine",
"name": "CNC-07 5-axis machining centre"
},
)
data = response.json(){
"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.
asset.deleteRequires If-MatchParameters
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"// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym", {
method: "DELETE",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag
},
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.delete(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
)
data = response.json()No bodyGet 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.
asset.readParameters
idpath · stringrequired- The ID of an asset of the tenant. Any other ID answers like a missing one.
Returns
The asset
Errors
curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
asset.updateRequires If-MatchParameters
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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "CNC-07 5-axis machining centre",
"asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"name": "CNC-07 5-axis machining centre",
"asset_type_id": "aty_01m71xxqhkf9avn6dq2sfgzgym"
},
)
data = response.json(){
"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.
asset.listParameters
idpath · stringrequired- The ID of an asset of the tenant. Any other ID answers like a missing one.
Returns
The ancestors
Errors
curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/ancestors \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/ancestors", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/ancestors",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
asset.listParameters
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
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"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/children?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/children?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
asset.listParameters
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
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"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/descendants?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/descendants?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
asset.updateIdempotent with keyRequires If-MatchParameters
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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/lifecycle", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"to": "standby"
}),
});
const data = await response.json();import os
import uuid
import requests
# etag: the ETag header of your last read of this resource
response = requests.post(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/lifecycle",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
"If-Match": etag,
},
json={
"to": "standby"
},
)
data = response.json(){
"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.
asset.moveIdempotent with keyRequires If-MatchAsynchronousParameters
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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/move", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID(),
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"new_parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc"
}),
});
const data = await response.json();import os
import uuid
import requests
# etag: the ETag header of your last read of this resource
response = requests.post(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/move",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
"If-Match": etag,
},
json={
"new_parent_id": "ast_01m71xxpcwfz1snpsm3pqdqrjc"
},
)
data = response.json(){
"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.
asset.deleteIdempotent with keyParameters
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
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)"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/restore", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Idempotency-Key": crypto.randomUUID()
},
});
const data = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/restore",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"Idempotency-Key": str(uuid.uuid4()),
},
)
data = response.json(){
"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.
shift.readParameters
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
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"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-at?at=2026-11-01T08:00:00Z", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-at?at=2026-11-01T08:00:00Z",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
shift.listParameters
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
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"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-windows?from_on=2026-11-01&to_on=2026-11-01", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/shift-windows?from_on=2026-11-01&to_on=2026-11-01",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
asset.listParameters
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
curl https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/tree \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/tree", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/assets/ast_01m71xxqhkf9avn6dq2sfgzgym/tree",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
clock_status.readParameters
limitquery · integer- The page size of a list, 1 to 500; the default is 50.
Returns
A page of clock statuses
Errors
curl https://api.hive.clerktree.com/v1/clock-statuses?limit=20 \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/clock-statuses?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/clock-statuses?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
clock_status.readParameters
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
curl https://api.hive.clerktree.com/v1/clock-statuses/string \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/clock-statuses/string", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/clock-statuses/string",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
time_exception.readParameters
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
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"const response = await fetch("https://api.hive.clerktree.com/v1/clock-statuses/string/exceptions?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/clock-statuses/string/exceptions?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
me.readReturns
The caller's tenants
Errors
curl https://api.hive.clerktree.com/v1/me/tenants \
-H "Authorization: Bearer $HIVE_USER_TOKEN" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/me/tenants", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_USER_TOKEN}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/me/tenants",
headers={
"Authorization": f"Bearer {os.environ['HIVE_USER_TOKEN']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
Returns
The verdict for each token
Errors
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"
}
]'const response = await fetch("https://api.hive.clerktree.com/v1/integrations/secret-scanning/github", {
method: "POST",
headers: {
"Hive-Version": "2026-11-01",
"Content-Type": "application/json"
},
body: JSON.stringify([
{
"source": "content",
"token": "hive_live_01m71xxng7fzrvspnkgtw1t2km_NotARealSecretNotARealSecretNotARealSecrXXXXXX",
"type": "hive_api_key",
"url": "https://github.com/example/musterwerk-integration/blob/main/.env"
}
]),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/integrations/secret-scanning/github",
headers={
"Hive-Version": "2026-11-01",
},
json=[
{
"source": "content",
"token": "hive_live_01m71xxng7fzrvspnkgtw1t2km_NotARealSecretNotARealSecretNotARealSecrXXXXXX",
"type": "hive_api_key",
"url": "https://github.com/example/musterwerk-integration/blob/main/.env"
}
],
)
data = response.json()[
{
"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.
membership.listParameters
limitquery · integer- The page size of a list, 1 to 500; the default is 50.
Returns
A page of memberships
Errors
curl https://api.hive.clerktree.com/v1/memberships?limit=20 \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/memberships?limit=20", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/memberships?limit=20",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
membership.updateRequires If-MatchParameters
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
# 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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/memberships/usr_01m71xxqhkf9avn6dq2sfgzgym", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"status": "suspended"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/memberships/usr_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"status": "suspended"
},
)
data = response.json(){
"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.
site.listReturns
The site profiles
Errors
curl https://api.hive.clerktree.com/v1/sites \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/sites", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/sites",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
site.updateRequires If-MatchParameters
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
# 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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/sites/ast_01m71xxqhkf9avn6dq2sfgzgym", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"address": {
"city": "Esslingen am Neckar",
"postal_code": "73730",
"street": "Plochinger Strasse 12"
},
"country_code": "DE",
"time_zone": "Europe/Berlin"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/sites/ast_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"address": {
"city": "Esslingen am Neckar",
"postal_code": "73730",
"street": "Plochinger Strasse 12"
},
"country_code": "DE",
"time_zone": "Europe/Berlin"
},
)
data = response.json(){
"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.
tenant.readReturns
The tenant
Errors
curl https://api.hive.clerktree.com/v1/tenants/current \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/tenants/current", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/tenants/current",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
tenant.updateRequires If-MatchParameters
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
# 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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/tenants/current", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"default_language": "en",
"display_name": "Musterwerk Esslingen"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/tenants/current",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"default_language": "en",
"display_name": "Musterwerk Esslingen"
},
)
data = response.json(){
"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.
tenant.readParameters
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
curl https://api.hive.clerktree.com/v1/tenants/ten_01m71xxqhkf9avn6dq2sfgzgym \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/tenants/ten_01m71xxqhkf9avn6dq2sfgzgym", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/tenants/ten_01m71xxqhkf9avn6dq2sfgzgym",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
time.readReturns
The cloud time
Errors
curl https://api.hive.clerktree.com/v1/time \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/time", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/time",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
unit.readReturns
The quantity kinds
Errors
curl https://api.hive.clerktree.com/v1/quantity-kinds \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/quantity-kinds", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/quantity-kinds",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
unit_preference.readReturns
The unit preferences
Errors
curl https://api.hive.clerktree.com/v1/unit-preferences \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/unit-preferences", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/unit-preferences",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
unit_preference.updateRequires If-MatchParameters
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
# 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"
}'// etag: the ETag header of your last read of this resource
const response = await fetch("https://api.hive.clerktree.com/v1/unit-preferences", {
method: "PATCH",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"If-Match": etag,
"Content-Type": "application/json"
},
body: JSON.stringify({
"display_units": {
"pressure": "bar",
"temperature": "Cel"
},
"rotational_speed_style": "din"
}),
});
const data = await response.json();import os
import requests
# etag: the ETag header of your last read of this resource
response = requests.patch(
"https://api.hive.clerktree.com/v1/unit-preferences",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
"If-Match": etag,
},
json={
"display_units": {
"pressure": "bar",
"temperature": "Cel"
},
"rotational_speed_style": "din"
},
)
data = response.json(){
"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.
unit.readParameters
kindquery · string- Only the units of this quantity kind (a slug of GET /v1/quantity-kinds).
Returns
The units
Errors
curl https://api.hive.clerktree.com/v1/units \
-H "Authorization: Bearer $HIVE_API_KEY" \
-H "Hive-Version: 2026-11-01"const response = await fetch("https://api.hive.clerktree.com/v1/units", {
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01"
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://api.hive.clerktree.com/v1/units",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
)
data = response.json(){
"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.
unit.readBody
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
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
}'const response = await fetch("https://api.hive.clerktree.com/v1/units/convert", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Content-Type": "application/json"
},
body: JSON.stringify({
"from": "bar",
"to": "[psi]",
"value": 5.4
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/units/convert",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
json={
"from": "bar",
"to": "[psi]",
"value": 5.4
},
)
data = response.json(){
"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.
unit.readBody
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
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
}'const response = await fetch("https://api.hive.clerktree.com/v1/units/format", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HIVE_API_KEY}`,
"Hive-Version": "2026-11-01",
"Content-Type": "application/json"
},
body: JSON.stringify({
"unit": "mm/s",
"value": 7.8
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://api.hive.clerktree.com/v1/units/format",
headers={
"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}",
"Hive-Version": "2026-11-01",
},
json={
"unit": "mm/s",
"value": 7.8
},
)
data = response.json(){
"object": "formatted_quantity",
"locale": "de",
"text": "7,8 mm/s",
"unit_label": "mm/s",
"value_text": "7,8"
}