API Reference

Integrate Hivekraft into your tools and workflows. Manage apiaries, hives, inspections, treatments, and IoT sensors programmatically.

18 modules · 104endpoints · REST · JSON

Get Started Quick Start Guide

Quick Start

Get up and running with the Hivekraft API in three steps.

1. Create your account

2. Generate an API key

Go to Settings > API in the dashboard. Click "Generate API Key" and copy the key. It starts with hk_live_ and is shown only once.

3. Make your first request

Use the key in the Authorization header as a Bearer token. Try listing your apiaries:

# Replace YOUR_API_KEY with the token from /dashboard/settings/api-keys
curl https://hivekraft.com/api/apiaries \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API endpoints require authentication via a Bearer token in the Authorization header.

Bearer Token

Include your API key in every request:

Authorization: Bearer YOUR_API_KEY

API keys start with hk_live_ and are tied to your user account. All requests are scoped to your data.

Rate Limits

API key requests are rate-limited to a default of 300 requests per minute. The effective limit depends on your plan and the endpoint (expensive AI endpoints have lower limits). Always read the X-RateLimit-Limit header for the value that applies to a given request.

Header	Description
`X-RateLimit-Limit`	Maximum requests per window for this request (default 300, lower for AI endpoints)
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Best Practices

Never expose your API key in client-side code or public repositories.
Use environment variables to store your key.
Rotate your API key periodically in Settings > API.
Implement exponential backoff when you receive 429 status codes.

AI-Powered Endpoints

Some endpoints generate content using AI (chat, photo analysis, design generation, voice transcription, label suggestions). These are marked with an inline disclaimer per EU AI Act Art. 50.

This chat uses AI (EU-hosted AI models). Answers may be inaccurate. Learn more

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validierungsfehler",
    "details": {
      "name": ["Name ist erforderlich"]
    }
  }
}

Status Codes

Code	Error Code	Description
`200`	-	Success
`201`	-	Created
`204`	-	No Content (successful DELETE)
`400`	VALIDATION_ERROR	Invalid request body or query parameters
`401`	UNAUTHORIZED	Missing or invalid authentication
`403`	FORBIDDEN	Insufficient permissions or plan upgrade required
`404`	NOT_FOUND	Resource not found
`409`	CONFLICT	Conflicting operation (e.g. duplicate)
`429`	RATE_LIMITED	Too many requests, retry after backoff
`500`	INTERNAL_ERROR	Unexpected server error

Response Envelope

Successful responses wrap data in a data field:

// Success (200/201)
{ "data": { "id": "clx1...", "name": "Waldbienenstand" } }

// Error (4xx/5xx)
{ "error": { "code": "NOT_FOUND", "message": "Nicht gefunden" } }

Apiaries

Manage your apiary locations (Standorte). Each apiary holds one or more hives.

GET/api/apiariesScope: read:apiaries

List all apiaries

Returns every apiary belonging to the authenticated user.

Example

curl -X GET "https://hivekraft.com/api/apiaries" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/apiariesScope: write:apiaries

Create an apiary

Creates a new apiary for the authenticated user.

Request Body

Field	Type	Description
`name`	string	Apiary name (required)e.g. `Waldbienenstand`
`address`	string	Street addresse.g. `Waldweg 12, 80331 München`
`latitude`	number	GPS latitude (-90..90)e.g. `48.137`
`longitude`	number	GPS longitude (-180..180)e.g. `11.576`
`registrationNumber`	string	Official registration numbere.g. `BY-123-456`
`notes`	string	Free-text notes (max 5000 chars)

Example

curl -X POST "https://hivekraft.com/api/apiaries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Waldbienenstand","latitude":48.137,"longitude":11.576}'

GET/api/apiaries/[id]Scope: read:apiaries

Get a single apiary

Returns full details for one apiary including hive count.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Apiary IDe.g. `clx1...`

Example

curl -X GET "https://hivekraft.com/api/apiaries/clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/apiaries/[id]Scope: write:apiaries

Update an apiary

Partially updates an existing apiary. Only include the fields you want to change.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Apiary ID

Request Body

Any subset of the create fields

Field	Type	Description
`name`	string	New name
`address`	string	New address
`latitude`	number	New latitude
`longitude`	number	New longitude

Example

curl -X PUT "https://hivekraft.com/api/apiaries/clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Neuer Name"}'

DELETE/api/apiaries/[id]Scope: write:apiaries

Delete an apiary

Permanently deletes an apiary. All hives must be removed or transferred first.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Apiary ID

Example

curl -X DELETE "https://hivekraft.com/api/apiaries/clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/apiaries/[id]/statisticsScope: read:apiaries

Get apiary statistics

Returns aggregated statistics for a single apiary including hive counts, honey totals, inspection count, and average colony strength.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Apiary ID

Example

curl -X GET "https://hivekraft.com/api/apiaries/clx1abc/statistics" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/apiaries/[id]/forecastScope: read:apiaries

Get harvest forecast (Pro)

Returns a harvest forecast for the apiary based on historical data and weather conditions. Requires Pro plan or higher.

Recommendations are based on statistical models and threshold rules (not generative AI). Please verify before applying. Learn more

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Apiary ID (must have GPS coordinates)

Example

curl -X GET "https://hivekraft.com/api/apiaries/clx1abc/forecast" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hives

Manage bee colonies (Völker). Each hive belongs to one apiary and may have a queen assigned.

GET/api/hivesScope: read:hives

List all hives

Returns all hives for the user. Supports filtering by apiary and status, plus cursor-based pagination. Without any pagination param the response is a bare array. As soon as you send `cursor` and/or `limit`, the response becomes a pagination object `{ items, nextCursor, hasMore }`.

Query Parameters

Name	Type	Required	Description
`apiaryId`	string	No	Filter by apiary
`status`	string	No	Filter by status (active, dead, sold, merged)
`cursor`	string	No	Pagination cursor — pass the `nextCursor` from the previous page to fetch the next batch
`limit`	number	No	Items per page (1-100, default 20). Sending this enables the paginated object response shape.

Response Body

Without pagination params: a bare array of hives. With `cursor`/`limit`: a pagination object `{ items: Hive[], nextCursor: string | null, hasMore: boolean }`. The example shows the paginated shape.

Field	Type	Description
`items`	array	The hives on this page
`nextCursor`	string	Cursor for the next page, or null when there are no more results
`hasMore`	boolean	True when a further page is available

Example

curl -X GET "https://hivekraft.com/api/hives?apiaryId=clx1abc&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/hivesScope: write:hives

Create a hive

Creates a new hive (colony) in the specified apiary.

Request Body

Field	Type	Description
`apiaryId`	string	Apiary to place the hive in (required)e.g. `clx1abc`
`number`	integer	Hive number, positive integer (required)e.g. `7`
`name`	string	Optional display namee.g. `Bienchen`
`hiveType`	string	dadant \| zander \| langstroth \| segeberger \| other (required)e.g. `dadant`
`origin`	string	swarm \| split \| purchase \| gift \| own \| other
`notes`	string	Free-text notes (max 5000 chars)

Example

curl -X POST "https://hivekraft.com/api/hives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiaryId":"clx1abc","number":7,"hiveType":"dadant","name":"Bienchen"}'

GET/api/hives/[id]Scope: read:hives

Get a single hive

Returns full details for one hive including queen and apiary info.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID

Example

curl -X GET "https://hivekraft.com/api/hives/clx2abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/hives/[id]Scope: write:hives

Update a hive

Partially updates hive details.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID

Example

curl -X PUT "https://hivekraft.com/api/hives/clx2abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Neuer Name"}'

DELETE/api/hives/[id]Scope: write:hives

Delete a hive

Soft-deletes a hive. It will no longer appear in listings.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID

Example

curl -X DELETE "https://hivekraft.com/api/hives/clx2abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/hives/[id]/healthScope: read:hives

Get hive health score

Calculates a health score (0-100) based on recent inspections, treatments, and queen status. Requires Pro plan.

Recommendations are based on statistical models and threshold rules (not generative AI). Please verify before applying. Learn more

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID

Example

curl -X GET "https://hivekraft.com/api/hives/clx2abc/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/hives/[id]/splitScope: write:hives

Split a hive (Ableger)

Creates a new colony from an existing hive by splitting it.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Source hive ID

Request Body

Field	Type	Description
`number`	integer	Hive number for the new colony (required)e.g. `8`
`name`	string	Optional display name for new colony
`hiveType`	string	Hive type for the new colony (required)e.g. `dadant`
`notes`	string	Notes about the split

Example

curl -X POST "https://hivekraft.com/api/hives/clx2abc/split" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":8,"hiveType":"dadant","name":"Ableger Mai"}'

POST/api/hives/[id]/transferScope: write:hives

Transfer hive to another apiary

Moves a hive from its current apiary to a different one. Records the movement.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID to transfer

Request Body

Field	Type	Description
`toApiaryId`	string	Target apiary ID (required)e.g. `clx1xyz`
`notes`	string	Notes about the transfer

Example

curl -X POST "https://hivekraft.com/api/hives/clx2abc/transfer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toApiaryId":"clx1xyz"}'

POST/api/hives/[id]/mark-deadScope: write:hives

Mark a hive as dead

Marks a colony as dead with optional cause, date, and notes. Sets the hive status to 'dead'.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Hive ID

Request Body

Field	Type	Description
`deathCause`	string	varroa \| starvation \| queen_loss \| pesticide \| disease \| winter_loss \| robbing \| unknown \| other
`deathDate`	string	Date of death (ISO date)e.g. `2025-12-15`
`deathNotes`	string	Notes about the death (max 5000 chars)

Example

curl -X POST "https://hivekraft.com/api/hives/clx2abc/mark-dead" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deathCause":"varroa","deathDate":"2025-12-15","deathNotes":"Weak colony in autumn"}'

GET/api/hives/health-overviewScope: read:hives

Get health overview for all hives

Returns health scores and swarm risk levels for all active hives. Includes score (0-100), risk level, and top contributing factor.

Recommendations are based on statistical models and threshold rules (not generative AI). Please verify before applying. Learn more

Example

curl -X GET "https://hivekraft.com/api/hives/health-overview" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/hives/swarm-riskScope: read:hives

Get swarm risk assessment

Returns swarm risk scores for all active hives based on recent inspection data, including risk factors and recommendations.

Recommendations are based on statistical models and threshold rules (not generative AI). Please verify before applying. Learn more

Example

curl -X GET "https://hivekraft.com/api/hives/swarm-risk" \
  -H "Authorization: Bearer YOUR_API_KEY"

Queens

Track queens (Königinnen) with lineage, traits, and assignment to hives.

GET/api/queensScope: read:queens

List all queens

Returns all queens. Supports filtering by hive and status.

Query Parameters

Name	Type	Required	Description
`hiveId`	string	No	Filter by assigned hive
`status`	string	No	Filter by status (active, dead, superseded, lost, sold)

Example

curl -X GET "https://hivekraft.com/api/queens?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/queensScope: write:queens

Create a queen

Registers a new queen. Optionally assign to a hive and record lineage.

Request Body

Field	Type	Description
`hiveId`	string	Assign to this hive (optional)
`race`	string	carnica \| buckfast \| ligustica \| mellifera \| caucasica \| othere.g. `carnica`
`birthYear`	integer	Year of birth (2000+)e.g. `2025`
`markingColor`	string	Marking colore.g. `blue`
`origin`	string	own \| purchased \| gifted \| swarm \| other
`breeder`	string	Breeder namee.g. `Belegstelle Hochalm`
`status`	string	active \| dead \| superseded \| lost \| sold
`gentleness`	integer	Trait rating 1-5
`honeyProduction`	integer	Trait rating 1-5
`motherQueenId`	string	ID of the mother queen for lineage tracking

Example

curl -X POST "https://hivekraft.com/api/queens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"race":"carnica","birthYear":2025,"markingColor":"blue","hiveId":"clx2abc"}'

GET/api/queens/[id]Scope: read:queens

Get a single queen

Returns full details including trait ratings and lineage.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Queen ID

Example

curl -X GET "https://hivekraft.com/api/queens/clx3abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/queens/[id]Scope: write:queens

Update a queen

Partially updates queen details including trait ratings.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Queen ID

Example

curl -X PUT "https://hivekraft.com/api/queens/clx3abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"superseded"}'

DELETE/api/queens/[id]Scope: write:queens

Delete a queen

Soft-deletes a queen record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Queen ID

Example

curl -X DELETE "https://hivekraft.com/api/queens/clx3abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/queens/[id]/assignScope: write:queens

Assign queen to a hive

Assigns a queen to a hive or unassigns it (pass null). Any previously assigned queen on the target hive is automatically unassigned.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Queen ID

Request Body

Field	Type	Description
`hiveId`	string\|null	Hive ID to assign to, or null to unassigne.g. `clx2abc`

Example

curl -X POST "https://hivekraft.com/api/queens/clx3abc/assign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hiveId":"clx2abc"}'

Inspections

Record hive inspections (Durchsichten) with colony strength, brood pattern, varroa counts, and more.

GET/api/inspectionsScope: read:inspections

List inspections

Returns inspections with optional filtering and cursor-based pagination. Without any pagination param the response is a bare array. As soon as you send `cursor` and/or `limit`, the response becomes a pagination object `{ items, nextCursor, hasMore }`.

Query Parameters

Name	Type	Required	Description
`hiveId`	string	No	Filter by hive
`type`	string	No	quick_check \| standard \| detailed
`dateFrom`	string	No	ISO date lower bounde.g. `2025-01-01`
`dateTo`	string	No	ISO date upper bounde.g. `2025-12-31`
`cursor`	string	No	Pagination cursor — pass the `nextCursor` from the previous page to fetch the next batch
`limit`	number	No	Items per page (1-100, default 20). Sending this enables the paginated object response shape.

Response Body

Without pagination params: a bare array of inspections. With `cursor`/`limit`: a pagination object `{ items: Inspection[], nextCursor: string | null, hasMore: boolean }`. The example shows the paginated shape.

Field	Type	Description
`items`	array	The inspections on this page
`nextCursor`	string	Cursor for the next page, or null when there are no more results
`hasMore`	boolean	True when a further page is available

Example

curl -X GET "https://hivekraft.com/api/inspections?hiveId=clx2abc&dateFrom=2025-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/inspectionsScope: write:inspections

Create an inspection

Records a new hive inspection with details about colony health, brood, varroa, and weather.

Request Body

Field	Type	Description
`hiveId`	string	Hive to inspect (required)e.g. `clx2abc`
`date`	string	Inspection date (required)e.g. `2025-06-15`
`type`	string	quick_check \| standard \| detailed (required)e.g. `standard`
`colonyStrength`	integer	Strength rating 1-10e.g. `8`
`queenSeen`	boolean	Was the queen spotted?e.g. `true`
`eggsSeen`	boolean	Were eggs visible?
`temperament`	string	calm \| nervous \| aggressive
`honeyStores`	string	empty \| low \| medium \| high \| very_high
`broodPattern`	string	none \| spotty \| average \| good \| excellent
`varroaCount`	integer	Varroa counte.g. `3`
`varroaMethod`	string	sugar_shake \| alcohol_wash \| natural_drop \| drone_brood
`notes`	string	Free-text notes (max 5000 chars)

Example

curl -X POST "https://hivekraft.com/api/inspections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hiveId":"clx2abc","date":"2025-06-15","type":"standard","colonyStrength":8,"queenSeen":true}'

GET/api/inspections/[id]Scope: read:inspections

Get a single inspection

Returns full inspection details including pest observations.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Example

curl -X GET "https://hivekraft.com/api/inspections/clx4abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/inspections/[id]Scope: write:inspections

Update an inspection

Partially updates inspection data.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Example

curl -X PUT "https://hivekraft.com/api/inspections/clx4abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"colonyStrength":9}'

DELETE/api/inspections/[id]Scope: write:inspections

Delete an inspection

Permanently removes an inspection record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Example

curl -X DELETE "https://hivekraft.com/api/inspections/clx4abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/inspections/[id]/photosScope: read:inspections

Get inspection photos

Returns all photos attached to an inspection.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Example

curl -X GET "https://hivekraft.com/api/inspections/clx4abc/photos" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/inspections/[id]/photosScope: write:inspections

Upload an inspection photo

Uploads a photo to an inspection. Uses multipart/form-data with fields: photo (file), photoType (string), caption (string).

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Request Body

multipart/form-data

Field	Type	Description
`photo`	file	Image file (required)
`photoType`	string	Photo type (e.g. brood, queen, general)
`caption`	string	Photo caption

Example

curl -X POST "https://hivekraft.com/api/inspections/clx4abc/photos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "photo=@brood.jpg" \
  -F "photoType=brood" \
  -F "caption=Good brood pattern"

DELETE/api/inspections/[id]/photosScope: write:inspections

Delete an inspection photo

Deletes a specific photo from an inspection. Pass the photoId as a query parameter.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Inspection ID

Query Parameters

Name	Type	Required	Description
`photoId`	string	Yes	Photo ID to delete

Example

curl -X DELETE "https://hivekraft.com/api/inspections/clx4abc/photos?photoId=clxpabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Treatments

Record varroa treatments (Behandlungen) with EU 2019/6 compliance fields for the colony record book.

GET/api/treatmentsScope: read:treatments

List treatments

Returns treatments with optional filters for hive, type, status, and date range.

Query Parameters

Name	Type	Required	Description
`hiveId`	string	No	Filter by hive
`treatmentType`	string	No	oxalic_acid \| formic_acid \| thymol \| apilife_var \| apiguard \| checkmite \| other
`status`	string	No	planned \| in_progress \| completed
`startDate`	string	No	Date range start
`endDate`	string	No	Date range end
`limit`	number	No	Max results

Example

curl -X GET "https://hivekraft.com/api/treatments?treatmentType=oxalic_acid" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/treatmentsScope: write:treatments

Create a treatment

Records a new varroa treatment. Includes optional EU 2019/6 compliance fields (batchNumber, supplier, veterinarian).

Request Body

Field	Type	Description
`hiveId`	string	Hive ID (required)e.g. `clx2abc`
`treatmentType`	string	Treatment type (required)e.g. `oxalic_acid`
`method`	string	trickling \| sublimation \| evaporation \| strips \| spray
`startDate`	string	Start date (required)e.g. `2025-12-01`
`endDate`	string	End date (multi-day treatments)
`dose`	number	Dosage amounte.g. `5`
`unit`	string	ml \| g \| strips \| pieces
`status`	string	planned \| in_progress \| completede.g. `completed`
`varroaCountBefore`	integer	Varroa count before treatment
`varroaCountAfter`	integer	Varroa count after treatment
`batchNumber`	string	EU: Batch/lot number of the medication
`supplier`	string	EU: Supplier name
`veterinarian`	string	EU: Veterinarian name
`prescriptionNumber`	string	EU: Prescription number
`withdrawalPeriodDays`	integer	EU: Withdrawal period in days
`notes`	string	Free-text notes

Example

curl -X POST "https://hivekraft.com/api/treatments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hiveId":"clx2abc","treatmentType":"oxalic_acid","method":"trickling","startDate":"2025-12-01","dose":5,"unit":"ml","status":"completed"}'

GET/api/treatments/[id]Scope: read:treatments

Get a single treatment

Returns full treatment details including compliance fields.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Treatment ID

Example

curl -X GET "https://hivekraft.com/api/treatments/clx5abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/treatments/[id]Scope: write:treatments

Update a treatment

Partially updates an existing treatment record. All fields are optional. Includes EU 2019/6 compliance fields.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Treatment ID

Request Body

Any subset of treatment fields

Field	Type	Description
`treatmentType`	string	oxalic_acid \| formic_acid \| thymol \| apilife_var \| apiguard \| bayvarol \| perizin \| other
`method`	string	spray \| trickle \| evaporation \| strip \| sublimation \| other
`startDate`	string	Start date (ISO)
`endDate`	string	End date (ISO)
`dose`	number	Dose amount (positive)
`unit`	string	ml \| g \| strips \| plates
`status`	string	planned \| in_progress \| completed \| cancelled
`notes`	string	Notes (max 5000 chars)
`varroaCountBefore`	integer	Varroa count before treatment
`varroaCountAfter`	integer	Varroa count after treatment
`effectiveness`	string	high \| medium \| low \| none
`batchNumber`	string	EU: Medication batch number
`supplier`	string	EU: Supplier name
`veterinarian`	string	EU: Veterinarian name

Example

curl -X PUT "https://hivekraft.com/api/treatments/clx5abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","varroaCountAfter":3,"effectiveness":"high"}'

DELETE/api/treatments/[id]Scope: write:treatments

Delete a treatment

Permanently removes a treatment record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Treatment ID

Example

curl -X DELETE "https://hivekraft.com/api/treatments/clx5abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Feedings

Track colony feedings (Fütterungen) with feed type and amounts.

GET/api/feedingsScope: read:feedings

List feedings

Returns all feeding records for the user.

Query Parameters

Name	Type	Required	Description
`hiveId`	string	No	Filter by hive

Example

curl -X GET "https://hivekraft.com/api/feedings?hiveId=clx2abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/feedingsScope: write:feedings

Create a feeding

Records a new feeding event for a colony.

Request Body

Field	Type	Description
`hiveId`	string	Hive ID (required)e.g. `clx2abc`
`feedType`	string	sugar_syrup \| fondant \| honey \| pollen_patty \| other (required)e.g. `sugar_syrup`
`amount`	number	Amount in kg (required)e.g. `2.5`
`date`	string	Feeding date (required)e.g. `2025-09-01`
`notes`	string	Free-text notes

Example

curl -X POST "https://hivekraft.com/api/feedings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hiveId":"clx2abc","feedType":"sugar_syrup","amount":2.5,"date":"2025-09-01"}'

GET/api/feedings/[id]Scope: read:feedings

Get a single feeding

Returns full details of a feeding record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Feeding ID

Example

curl -X GET "https://hivekraft.com/api/feedings/clx6abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/feedings/[id]Scope: write:feedings

Update a feeding

Partially updates an existing feeding record. All fields are optional.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Feeding ID

Request Body

Any subset of feeding fields

Field	Type	Description
`feedType`	string	sugar_syrup \| fondant \| honey \| pollen_patty \| other
`amount`	number	Amount in kg (positive)
`date`	string	Feeding date (ISO)e.g. `2025-09-15`
`notes`	string	Notes (max 5000 chars)

Example

curl -X PUT "https://hivekraft.com/api/feedings/clx6abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":3.0,"notes":"Increased dose"}'

DELETE/api/feedings/[id]Scope: write:feedings

Delete a feeding

Permanently removes a feeding record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Feeding ID

Example

curl -X DELETE "https://hivekraft.com/api/feedings/clx6abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Harvests

Record honey harvests (Ernten) with weight, water content, and honey type.

GET/api/harvestsScope: read:harvests

List harvests

Returns all harvests for the authenticated user.

Example

curl -X GET "https://hivekraft.com/api/harvests" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/harvestsScope: write:harvests

Create a harvest

Records a new honey harvest, optionally linked to specific hives.

Request Body

Field	Type	Description
`harvestDate`	string	Harvest date (required)e.g. `2025-07-10`
`honeyType`	string	rapeseed \| linden \| acacia \| forest \| wildflower \| summer \| spring \| othere.g. `rapeseed`
`netWeight`	number	Net weight in kg (required)e.g. `22.5`
`waterContent`	number	Water content % (0-30)e.g. `17.2`
`apiaryId`	string	Associated apiary
`hiveIds`	array	Array of hive IDs that contributed
`notes`	string	Free-text notes

Example

curl -X POST "https://hivekraft.com/api/harvests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"harvestDate":"2025-07-10","honeyType":"rapeseed","netWeight":22.5,"waterContent":17.2}'

GET/api/harvests/[id]Scope: read:harvests

Get a single harvest

Returns full details for one harvest record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Harvest ID

Example

curl -X GET "https://hivekraft.com/api/harvests/clx7abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/harvests/[id]Scope: write:harvests

Update a harvest

Partially updates an existing harvest record. All fields are optional.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Harvest ID

Request Body

Any subset of harvest fields

Field	Type	Description
`apiaryId`	string	Apiary ID
`harvestDate`	string	Harvest date (ISO)e.g. `2025-07-10`
`honeyType`	string	rapeseed \| acacia \| linden \| wildflower \| forest \| heather \| chestnut \| other
`netWeight`	number	Net weight in kg (positive)
`waterContent`	number	Water content % (0-30)
`hiveIds`	array	Array of hive IDs contributing to the harvest
`notes`	string	Notes (max 5000 chars)

Example

curl -X PUT "https://hivekraft.com/api/harvests/clx7abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"netWeight":24.0,"waterContent":16.8}'

DELETE/api/harvests/[id]Scope: write:harvests

Delete a harvest

Soft-deletes a harvest record.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Harvest ID

Example

curl -X DELETE "https://hivekraft.com/api/harvests/clx7abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bottling

Manage honey bottling batches (Abfüllung) with jar sizes, counts, and harvest traceability.

GET/api/bottlingScope: read:harvests

List bottling batches

Returns all bottling batches for the user.

Example

curl -X GET "https://hivekraft.com/api/bottling" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/bottlingScope: write:harvests

Create a bottling batch

Records a new bottling batch, optionally linking to harvests for traceability.

Request Body

Field	Type	Description
`bottlingDate`	string	Bottling date (required)e.g. `2025-07-15`
`honeyType`	string	Honey typee.g. `rapeseed`
`totalWeight`	number	Total weight in kg (required)e.g. `20.0`
`jarSize`	integer	250 or 500 (ml, required)e.g. `500`
`jarCount`	integer	Number of jars (required)e.g. `40`
`origin`	string	Origin label texte.g. `Waldbienenstand, München`
`bestBefore`	string	Best-before date
`harvests`	array	Array of {harvestId, weight} for traceability

Example

curl -X POST "https://hivekraft.com/api/bottling" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bottlingDate":"2025-07-15","totalWeight":20,"jarSize":500,"jarCount":40}'

GET/api/bottling/[id]Scope: read:harvests

Get a bottling batch

Returns full bottling details including linked harvests.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Bottling ID

Example

curl -X GET "https://hivekraft.com/api/bottling/clx8abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/bottling/[id]Scope: write:harvests

Update a bottling batch

Partially updates an existing bottling batch. All fields are optional.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Bottling ID

Request Body

Any subset of bottling fields

Field	Type	Description
`bottlingDate`	string	Bottling date (ISO)e.g. `2025-07-15`
`honeyType`	string	Honey type
`totalWeight`	number	Total weight in kg (positive)
`jarSize`	integer	Jar size: 250 or 500 (grams)
`jarCount`	integer	Number of jars (positive)

Example

curl -X PUT "https://hivekraft.com/api/bottling/clx8abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jarCount":45,"honeyType":"rapeseed"}'

DELETE/api/bottling/[id]Scope: write:harvests

Delete a bottling batch

Permanently removes a bottling batch.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Bottling ID

Example

curl -X DELETE "https://hivekraft.com/api/bottling/clx8abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Inventory Items

Track beekeeping equipment and supplies (Inventar) with stock levels and minimum thresholds.

GET/api/inventory/itemsScope: any read:* scope

List inventory items

Returns all inventory items across all storage locations.

Example

curl -X GET "https://hivekraft.com/api/inventory/items" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/inventory/itemsScope: full-access key

Create an inventory item

Adds a new item to the inventory.

Request Body

Field	Type	Description
`locationId`	string	Storage location (required)e.g. `clxa...`
`name`	string	Item name (required)e.g. `Dadant-Rähmchen`
`category`	string	frames \| boxes \| tools \| medication \| feed \| jars \| labels \| clothing \| other (required)e.g. `frames`
`quantity`	integer	Current stock counte.g. `120`
`unit`	string	Unit of measuremente.g. `Stück`
`minStock`	integer	Minimum stock alert thresholde.g. `50`
`notes`	string	Free-text notes

Example

curl -X POST "https://hivekraft.com/api/inventory/items" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locationId":"clxabc","name":"Dadant-Rähmchen","category":"frames","quantity":120,"minStock":50}'

GET/api/inventory/items/[id]Scope: any read:* scope

Get an inventory item

Returns full item details.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Item ID

Example

curl -X GET "https://hivekraft.com/api/inventory/items/clx9abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/inventory/items/[id]Scope: full-access key

Update an inventory item

Partially updates item details.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Item ID

Example

curl -X PUT "https://hivekraft.com/api/inventory/items/clx9abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":100}'

DELETE/api/inventory/items/[id]Scope: full-access key

Delete an inventory item

Permanently removes an inventory item.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Item ID

Example

curl -X DELETE "https://hivekraft.com/api/inventory/items/clx9abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Inventory Locations

Manage storage locations (Lagerorte) for your beekeeping equipment.

GET/api/inventory/locationsScope: any read:* scope

List storage locations

Returns all storage locations.

Example

curl -X GET "https://hivekraft.com/api/inventory/locations" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/inventory/locationsScope: full-access key

Create a storage location

Adds a new storage location.

Request Body

Field	Type	Description
`name`	string	Location name (required)e.g. `Werkstatt`
`type`	string	workshop \| garage \| shed \| cellar \| attic \| container \| other (required)e.g. `workshop`
`notes`	string	Free-text notes

Example

curl -X POST "https://hivekraft.com/api/inventory/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Werkstatt","type":"workshop"}'

GET/api/inventory/locations/[id]Scope: any read:* scope

Get a storage location

Returns location details including item count.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Location ID

Example

curl -X GET "https://hivekraft.com/api/inventory/locations/clxaabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/inventory/locations/[id]Scope: full-access key

Update a storage location

Partially updates a storage location. All fields are optional.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Location ID

Request Body

Any subset of location fields

Field	Type	Description
`name`	string	Location name (max 100 chars)
`type`	string	workshop \| garage \| shed \| cellar \| attic \| container \| other
`notes`	string	Free-text notes (max 2000 chars)

Example

curl -X PUT "https://hivekraft.com/api/inventory/locations/clxaabc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Neue Werkstatt","type":"workshop"}'

DELETE/api/inventory/locations/[id]Scope: full-access key

Delete a storage location

Removes a storage location. Must be empty first.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Location ID

Example

curl -X DELETE "https://hivekraft.com/api/inventory/locations/clxaabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Finance

Track beekeeping income and expenses (Finanzen) with categories and yearly overview.

GET/api/financeScope: read:finance

Get financial overview

Returns income, expenses, and balance for the specified year.

Query Parameters

Name	Type	Required	Description
`year`	integer	No	Filter by year (defaults to current year)e.g. `2025`

Example

curl -X GET "https://hivekraft.com/api/finance?year=2025" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/financeScope: write:finance

Create a finance entry

Records a new income or expense entry.

Request Body

Field	Type	Description
`type`	string	income \| expense (required)e.g. `income`
`category`	string	Category (honey_sales, equipment, medication, feed, etc., required)e.g. `honey_sales`
`amount`	number	Positive amount (required)e.g. `350`
`description`	string	Description (required)e.g. `Rapshonig Verkauf 15 Gläser`
`date`	string	Date (required)e.g. `2025-07-20`

Example

curl -X POST "https://hivekraft.com/api/finance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"income","category":"honey_sales","amount":350,"description":"Rapshonig Verkauf","date":"2025-07-20"}'

DELETE/api/financeScope: write:finance

Delete a finance entry

Deletes a finance entry by ID passed as a query parameter.

Query Parameters

Name	Type	Required	Description
`entryId`	string	Yes	Finance entry ID to delete

Example

curl -X DELETE "https://hivekraft.com/api/finance?entryId=clxfabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tasks

Manage beekeeping tasks (Aufgaben) with priorities, due dates, and recurring schedules.

GET/api/tasksScope: read:tasks

List tasks

Returns tasks with optional filtering by status, type, and priority.

Query Parameters

Name	Type	Required	Description
`status`	string	No	pending \| in_progress \| completed \| skipped
`type`	string	No	inspection \| treatment \| feeding \| harvest \| custom \| seasonal
`priority`	string	No	low \| medium \| high \| urgent

Example

curl -X GET "https://hivekraft.com/api/tasks?status=pending&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/tasksScope: write:tasks

Create a task

Creates a new beekeeping task, optionally linked to a hive or apiary.

Request Body

Field	Type	Description
`title`	string	Task title (required)e.g. `Varroabehandlung Volk 3`
`description`	string	Detailed description
`hiveId`	string	Link to a hive
`apiaryId`	string	Link to an apiary
`type`	string	inspection \| treatment \| feeding \| harvest \| custom \| seasonale.g. `treatment`
`priority`	string	low \| medium \| high \| urgente.g. `high`
`dueDate`	string	Due datee.g. `2025-08-01`
`isRecurring`	boolean	Whether the task repeats

Example

curl -X POST "https://hivekraft.com/api/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Varroabehandlung Volk 3","type":"treatment","priority":"high","dueDate":"2025-08-01"}'

PUT/api/tasks/[id]Scope: write:tasks

Update a task

Partially updates a task. Use this to mark tasks as completed.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Task ID

Example

curl -X PUT "https://hivekraft.com/api/tasks/clxbabc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed"}'

GET/api/tasks/[id]Scope: read:tasks

Get a single task

Returns full details for one task.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Task ID

Example

curl -X GET "https://hivekraft.com/api/tasks/clxbabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/api/tasks/[id]Scope: write:tasks

Delete a task

Permanently removes a task.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Task ID

Example

curl -X DELETE "https://hivekraft.com/api/tasks/clxbabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/tasks/seasonalScope: write:tasks

Generate seasonal tasks

Auto-generates seasonal beekeeping tasks based on the current date, location, and colony status. Returns the list of newly created tasks.

Example

curl -X POST "https://hivekraft.com/api/tasks/seasonal" \
  -H "Authorization: Bearer YOUR_API_KEY"

IoT Devices

Manage IoT sensor devices (hive scales, temperature sensors) and their readings.

GET/api/iot/devicesScope: read:iot

List IoT devices

Returns all IoT devices with optional filtering.

Query Parameters

Name	Type	Required	Description
`status`	string	No	active \| offline \| maintenance
`deviceType`	string	No	scale \| temp_sensor \| bee_counter \| gps_tracker
`hiveId`	string	No	Filter by assigned hive
`dataSource`	string	No	direct \| thingspeak \| csv

Example

curl -X GET "https://hivekraft.com/api/iot/devices?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/iot/devicesScope: write:iot

Create an IoT device

Registers a new IoT device. Supports direct push, ThingSpeak, and CSV data sources. Device limits: Free=3, Pro=10, Business=unlimited.

Request Body

Field	Type	Description
`name`	string	Device name (required)e.g. `Waage Volk 1`
`deviceType`	string	scale \| temp_sensor \| bee_counter \| gps_tracker (required)e.g. `scale`
`dataSource`	string	direct \| thingspeak \| csv (required)e.g. `direct`
`manufacturer`	string	Manufacturer namee.g. `HiveTool`
`hiveId`	string	Assign to a hive
`readingIntervalMinutes`	integer	Expected reading interval (1-1440, default 15)e.g. `15`

Example

curl -X POST "https://hivekraft.com/api/iot/devices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Waage Volk 1","deviceType":"scale","dataSource":"direct"}'

GET/api/iot/devices/[id]Scope: read:iot

Get an IoT device

Returns device details including latest reading.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Example

curl -X GET "https://hivekraft.com/api/iot/devices/clxcabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/iot/devices/[id]Scope: write:iot

Update an IoT device

Updates device configuration.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Example

curl -X PUT "https://hivekraft.com/api/iot/devices/clxcabc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Waage Volk 2","hiveId":"clx2xyz"}'

DELETE/api/iot/devices/[id]Scope: write:iot

Delete an IoT device

Removes an IoT device and all its readings.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Example

curl -X DELETE "https://hivekraft.com/api/iot/devices/clxcabc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/iot/devices/[id]/readingsScope: read:iot

Get device readings

Returns sensor readings for a device with optional time range filtering and daily aggregation. Without cursor the response is a bare array (chronologically ascending; X-List-Has-More / X-List-Next-Cursor headers signal further pages). With cursor the response is an object { items, nextCursor, hasMore } with items newest-first (keyset pagination).

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Query Parameters

Name	Type	Required	Description
`from`	string	No	Start date (ISO)e.g. `2025-06-01`
`to`	string	No	End date (ISO)e.g. `2025-06-30`
`limit`	integer	No	Max readings to return (default 500, max 2000)
`cursor`	string	No	Keyset cursor: pass the nextCursor of the previous page. Switches the response to { items, nextCursor, hasMore }
`offset`	integer	No	Deprecated — use cursor instead (ignored when cursor is set)
`aggregate`	string	No	Set to "daily" for daily aggregates

Example

curl -X GET "https://hivekraft.com/api/iot/devices/clxcabc/readings?from=2025-06-01&to=2025-06-30&aggregate=daily" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/iot/devices/[id]/syncScope: write:iot

Sync ThingSpeak device

Manually triggers a data sync for a ThingSpeak-connected device.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Example

curl -X POST "https://hivekraft.com/api/iot/devices/clxcabc/sync" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/iot/devices/[id]/assignScope: write:iot

Assign device to a hive

Assigns an IoT device to a hive or unassigns it (pass null).

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Request Body

Field	Type	Description
`hiveId`	string\|null	Hive ID to assign to, or null to unassigne.g. `clx2abc`

Example

curl -X POST "https://hivekraft.com/api/iot/devices/clxcabc/assign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hiveId":"clx2abc"}'

POST/api/iot/devices/[id]/importScope: write:iot

Import CSV readings

Imports sensor readings from a CSV file (max 5 MB). Uses multipart/form-data with a file and a JSON config for column mapping.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Device ID

Request Body

multipart/form-data

Field	Type	Description
`file`	file	CSV file (required, max 5 MB)
`config`	string	JSON config with mapping (column indices), timestampFormat (iso\|unix\|european\|american), timezoneOffset (-720..720)

Example

curl -X POST "https://hivekraft.com/api/iot/devices/clxcabc/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@readings.csv" \
  -F 'config={"mapping":{"timestamp":0,"weight":1,"temperature":2},"timestampFormat":"iso"}'

GET/api/iot/alertsScope: read:iot

List IoT alerts

Returns IoT device alerts (e.g. weight drop, temperature anomaly). Optionally filter to unread only.

Query Parameters

Name	Type	Required	Description
`unread`	boolean	No	Filter to unread alerts only (default: false)

Example

curl -X GET "https://hivekraft.com/api/iot/alerts?unread=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

PATCH/api/iot/alertsScope: write:iot

Update an IoT alert

Marks an alert as read or resolves it.

Request Body

Field	Type	Description
`alertId`	string	Alert ID (required)e.g. `clxaabc`
`action`	string	read \| resolve (required)e.g. `read`

Example

curl -X PATCH "https://hivekraft.com/api/iot/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alertId":"clxaabc","action":"resolve"}'

POST/api/iot/syncScope: write:iot

Sync all ThingSpeak devices

Triggers a data sync for all ThingSpeak-connected devices belonging to the user.

Example

curl -X POST "https://hivekraft.com/api/iot/sync" \
  -H "Authorization: Bearer YOUR_API_KEY"

IoT Push

Push sensor data from IoT devices. Uses device-specific X-API-Key header instead of Bearer token.

POST/api/iot/pushScope: write:iot

Push a sensor reading

Pushes a single sensor reading from a device. Authenticates via X-API-Key header (device API key, not user API key). Rate limit: 60 requests/minute.

Request Body

Field	Type	Description
`deviceId`	string	Device ID (required)e.g. `clxcabc`
`timestamp`	string	Reading timestamp (defaults to now)e.g. `2025-06-15T12:00:00Z`
`weight`	number	Weight in kge.g. `42.3`
`temperature`	number	Outer temperature in °Ce.g. `24.5`
`tempInner`	number	Inner hive temperature in °Ce.g. `35.1`
`humidity`	number	Humidity % (0-100)e.g. `62`
`batteryVoltage`	number	Battery voltagee.g. `3.7`

Example

curl -X POST "https://hivekraft.com/api/iot/push" \
  -H "X-API-Key: device_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"clxcabc","weight":42.3,"temperature":24.5,"humidity":62}'

POST/api/iot/push/batchScope: write:iot

Push a batch of readings

Pushes up to 100 sensor readings at once. Useful for buffered devices that go offline. Rate limit: 10 requests/minute.

Request Body

Field	Type	Description
`readings`	array	Array of reading objects (1-100, required)

Example

curl -X POST "https://hivekraft.com/api/iot/push/batch" \
  -H "X-API-Key: device_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"readings":[{"deviceId":"clxcabc","weight":42.3},{"deviceId":"clxcabc","weight":42.4}]}'

Compliance

EU 2019/6 colony record book (Bestandsbuch) compliance checks, history, and exports.

GET/api/compliance/checksScope: read:treatments

Get compliance status

Returns the latest compliance check result or full check history.

Query Parameters

Name	Type	Required	Description
`history`	boolean	No	Set to "true" to get full history

Example

curl -X GET "https://hivekraft.com/api/compliance/checks" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/compliance/exportScope: export:csv

Export compliance data

Exports compliance entries as JSON or CSV. CSV export requires Pro plan.

Query Parameters

Name	Type	Required	Description
`format`	string	No	json (default) \| csv
`hiveId`	string	No	Filter by hive
`apiaryId`	string	No	Filter by apiary
`startDate`	string	No	Date range start
`endDate`	string	No	Date range end

Example

curl -X GET "https://hivekraft.com/api/compliance/export?format=csv&startDate=2025-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/compliance/pdfScope: export:csv

Export as PDF (Bestandsbuch)

Generates a bilingual PDF colony record book. Free users: 1 PDF/month. Pro/Business: unlimited.

Query Parameters

Name	Type	Required	Description
`year`	integer	No	Year to export (default: current year)e.g. `2025`
`locale`	string	No	de \| en (default: de)

Example

curl -X GET "https://hivekraft.com/api/compliance/pdf?year=2025&locale=de" \
  -H "Authorization: Bearer YOUR_API_KEY" -o Bestandsbuch-2025.pdf

GET/api/complianceScope: read:treatments

List compliance entries

Returns compliance-relevant treatment entries with all EU required fields.

Query Parameters

Name	Type	Required	Description
`hiveId`	string	No	Filter by hive
`apiaryId`	string	No	Filter by apiary
`startDate`	string	No	Date range start
`endDate`	string	No	Date range end

Example

curl -X GET "https://hivekraft.com/api/compliance?apiaryId=clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/compliance/checksScope: write:treatments

Run a compliance check

Triggers a full EU 2019/6 compliance check across all colonies and returns the result with score and issues.

Example

curl -X POST "https://hivekraft.com/api/compliance/checks" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/compliance/vet-reportScope: read:treatments

Export veterinary report PDF

Generates a bilingual veterinary report PDF with all treatment data for the specified year.

Query Parameters

Name	Type	Required	Description
`year`	integer	No	Year to export (default: current year)e.g. `2025`
`locale`	string	No	de \| en (default: de)

Example

curl -X GET "https://hivekraft.com/api/compliance/vet-report?year=2025&locale=de" \
  -H "Authorization: Bearer YOUR_API_KEY" -o Veterinaerbericht-2025.pdf

Phenology

Growing degree days (GTS), bloom reports, treatment windows, and harvest timing based on phenological data.

GET/api/phenology/gtsScope: read:weather

Get GTS dashboard data

Returns growing degree sum (Grünland-Temperatursumme) for all apiaries with phenological phase indicators.

Example

curl -X GET "https://hivekraft.com/api/phenology/gts" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/phenology/bloom-reportsScope: read:weather

Get regional bloom reports

Returns bloom reports from the community near the given coordinates.

Query Parameters

Name	Type	Required	Description
`lat`	number	Yes	Latitudee.g. `48.137`
`lng`	number	Yes	Longitudee.g. `11.576`
`radius`	number	No	Search radius in km (0.1-500)e.g. `25`

Example

curl -X GET "https://hivekraft.com/api/phenology/bloom-reports?lat=48.137&lng=11.576&radius=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/phenology/bloom-reportsScope: write:weather

Submit a bloom report

Reports a plant bloom observation at your location. Notes are AI-moderated.

Request Body

Field	Type	Description
`plantName`	string	Plant name (required)e.g. `Raps`
`bloomStage`	string	Bloom stagee.g. `full_bloom`
`latitude`	number	Observation latitude
`longitude`	number	Observation longitude
`note`	string	Optional observation note

Example

curl -X POST "https://hivekraft.com/api/phenology/bloom-reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plantName":"Raps","bloomStage":"full_bloom","latitude":48.137,"longitude":11.576}'

GET/api/phenology/treatment-windowsScope: read:weather

Get treatment windows

Returns recommended treatment windows based on phenological conditions.

Example

curl -X GET "https://hivekraft.com/api/phenology/treatment-windows" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/phenology/harvest-timingScope: read:weather

Get harvest timing

Returns recommended harvest timing based on bloom data and weather conditions.

Example

curl -X GET "https://hivekraft.com/api/phenology/harvest-timing" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/phenology/todayScope: read:weather

Get daily phenology tasks

Returns phenology-based daily tasks and recommendations for the current date. Cached for 1 hour.

Example

curl -X GET "https://hivekraft.com/api/phenology/today" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/phenology/bloom/[apiaryId]Scope: read:weather

Get bloom data for an apiary

Returns current bloom data (flowering plants, nectar flow) for a specific apiary location.

Path Parameters

Name	Type	Required	Description
`apiaryId`	string	Yes	Apiary ID

Example

curl -X GET "https://hivekraft.com/api/phenology/bloom/clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/phenology/anomaliesScope: read:weather

Detect phenological anomalies

Analyzes phenological data to detect anomalies such as unusual bloom timing, temperature deviations, or unexpected nectar flow patterns.

Example

curl -X GET "https://hivekraft.com/api/phenology/anomalies" \
  -H "Authorization: Bearer YOUR_API_KEY"

Weather

Weather forecasts and alerts for your apiary locations. Powered by DWD (Bright Sky).

GET/api/weather/[apiaryId]Scope: read:weather

Get weather forecast

Returns the weather forecast for a specific apiary based on its GPS coordinates.

Path Parameters

Name	Type	Required	Description
`apiaryId`	string	Yes	Apiary ID (must have GPS coordinates)

Example

curl -X GET "https://hivekraft.com/api/weather/clx1abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/weather/alertsScope: read:weather

Get weather alerts

Returns active weather alerts (frost, heat, heavy rain, strong wind) for all apiaries.

Query Parameters

Name	Type	Required	Description
`locale`	string	No	de \| en (default: de)

Example

curl -X GET "https://hivekraft.com/api/weather/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Varroa

Varroa mite monitoring data, trend analysis, and treatment effectiveness tracking.

GET/api/varroaScope: read:treatments

Get varroa data

Returns varroa monitoring data across all hives.

Example

curl -X GET "https://hivekraft.com/api/varroa" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/varroa/trendsScope: read:treatments

Get varroa trends

Returns varroa count trends over time for all hives.

Example

curl -X GET "https://hivekraft.com/api/varroa/trends" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/varroa/effectivenessScope: read:treatments

Get treatment effectiveness

Analyzes the effectiveness of past varroa treatments.

Example

curl -X GET "https://hivekraft.com/api/varroa/effectiveness" \
  -H "Authorization: Bearer YOUR_API_KEY"