# Hydrobit API

Comprehensive API documentation for the Hydrobit platform.

This API enables management of forms, records, workers, projects, and related data within Hydrobit.

## Authentication
- **User endpoints:** Require a JWT in the `Authorization` header (Bearer token).

## Features
- Form management and record submission
- Project and sector data retrieval
- Worker management and operations
- Production session and record management

> **Note:** API access is available for Corporate accounts. For access or support, contact support@hydrobit.ag.


Version: 2.0.0
License: Proprietary

## Servers

Production server
```
https://api.hydrobit.ag
```

IoT server
```
https://iot.hydrobit.ag
```

MQTT over WebSocket endpoint
```
wss://iot.hydrobit.ag
```

## Security

### bearerAuth

JWT token for authentication

Type: http
Scheme: bearer
Bearer Format: JWT

### apiKeyAuth

Static or scoped API token for IoT data endpoints (weather, plant, irrigation)

Type: apiKey
In: header
Name: x-api-key

### iotToken

Short-lived token for MQTT over WebSocket authentication

Type: apiKey
In: header
Name: x-iot-token

## Download OpenAPI description

[Hydrobit API](https://docs.hydrobit.ag/_bundle/spec/openapi.yaml)

## Forms

Endpoints for form management and record submission

### Get forms for a user

 - [GET /api/control/forms/getForms](https://docs.hydrobit.ag/spec/openapi/forms/getforms.md): Retrieves all forms accessible to a user based on their company context.

Requires JWT token authentication in the Authorization header.

- If subtype=tasks, returns all task forms for the user
- Otherwise, returns monitoring forms based on user access permissions

### Submit a form record

 - [POST /api/control/forms/record](https://docs.hydrobit.ag/spec/openapi/forms/submitrecord.md): Submits a new form record with field values and location data.

This endpoint:
- Validates the record data
- Processes form field values
- Determines location (project/sector) using GPS or forced location
- Saves data to persistent storage
- Uploads media files (photos, audio, signatures) to cloud storage
- Updates task status if applicable

## Projects

Endpoints for project and sector data retrieval

### Get projects with sectors

 - [GET /api/control/projects](https://docs.hydrobit.ag/spec/openapi/projects/getprojects.md): Retrieves all projects for the authenticated user's company with nested sector information.

Requires JWT token authentication in the Authorization header.

This endpoint:
- Automatically resolves the user's company context from their JWT token
- Returns all projects associated with the company
- For each project, includes nested sectors with only name and sectorId fields
- Only returns projectId and projectName for each project

## Workers

Endpoints for worker management and operations

### Create a new worker

 - [POST /api/control/workers](https://docs.hydrobit.ag/spec/openapi/workers/createworker.md): Creates a new worker record with automatic ID generation and optional photo upload.

Key features:
- Worker ID is auto-generated as INITIALS + MMDD (from hire date)
- Requires JWT token authentication in the Authorization header
- Company context is inferred from the authenticated user
- Validates position, employment_type, and status against template options
- Ensures worker_id uniqueness per company (idempotent on duplicate)
- Supports photo upload via base64 data URL (JPEG, PNG, WebP up to 12MB)
- Photos are uploaded to cloud storage and URL is returned in response

### Get list of workers

 - [GET /api/control/workers](https://docs.hydrobit.ag/spec/openapi/workers/listworkers.md): Retrieves a paginated list of workers for the authenticated user's company.

Features:
- Requires JWT token authentication in the Authorization header
- Company context is inferred from the authenticated user
- Supports search by name or worker_id using the 'q' parameter
- Filter by status, position, or employment_type
- Pagination with customizable page size (default 25, max 100)
- Results sorted by creation date (newest first)

### Get a single worker

 - [GET /api/control/workers/{worker}](https://docs.hydrobit.ag/spec/openapi/workers/getworker.md): Retrieves detailed information about a specific worker by unique identifier or worker_id.

Features:
- Requires JWT token authentication in the Authorization header
- Company context is inferred from the authenticated user
- Can fetch by unique identifier or by worker_id (e.g., "JS0315")
- Returns full worker details including all fields

## Production Sessions

Endpoints for managing production sessions (open, close, update)

### Create a new production session

 - [POST /api/control/production/sessions](https://docs.hydrobit.ag/spec/openapi/production-sessions/createproductionsession.md): Opens a new production session for a specific project, sector, and day.

Requires JWT token authentication in the Authorization header.

Key features:
- Automatically resolves company context from authenticated user
- Resolves project timezone for day normalization
- Ensures uniqueness: only one open session per (company, project, day, sector)
- Supports custom pricing, bonuses, and duration settings
- Defaults are inherited from project configuration if not provided

### Get a production session

 - [GET /api/control/production/sessions/{sessionId}](https://docs.hydrobit.ag/spec/openapi/production-sessions/getproductionsession.md): Retrieves detailed information about a specific production session.

Requires JWT token authentication in the Authorization header.

Only the session owner (user who opened it) can view the session.

### Update session metadata

 - [PATCH /api/control/production/sessions/{sessionId}](https://docs.hydrobit.ag/spec/openapi/production-sessions/updateproductionsession.md): Updates metadata of an open production session.

Requires JWT token authentication in the Authorization header.

Only the session owner can update. Session must be open.

Updatable fields: samplingUnit, pricePerUnit, bonus, notes

### Close a production session

 - [POST /api/control/production/sessions/{sessionId}/close](https://docs.hydrobit.ag/spec/openapi/production-sessions/closeproductionsession.md): Closes an open production session.

Requires JWT token authentication in the Authorization header.

Only the session owner can close it. Session must be open.

### Extend session duration

 - [POST /api/control/production/sessions/{sessionId}/extend](https://docs.hydrobit.ag/spec/openapi/production-sessions/extendproductionsession.md): Extends the maximum duration of an open production session.

Requires JWT token authentication in the Authorization header.

Only the session owner can extend it. Session must be open.

## Production Records

Endpoints for creating and managing production records

### Create a production record

 - [POST /api/control/production/records](https://docs.hydrobit.ag/spec/openapi/production-records/createproductionrecord.md): Creates a new production record to add units to an open session.

Requires JWT token authentication in the Authorization header.

Key features:
- Only the session owner can create records
- Session must be open
- Supports idempotency via clientEventId and optional idempotencyKey
- Optimized for high-performance processing

### Bulk create production records

 - [POST /api/control/production/records/bulk](https://docs.hydrobit.ag/spec/openapi/production-records/bulkcreateproductionrecords.md): Creates multiple production records in a single request (offline sync).

Requires JWT token authentication in the Authorization header.

Each record is processed independently with full validation and idempotency.
Returns multi-status response (207) with individual results.

### Check idempotency key

 - [HEAD /api/control/production/records/check-idempotency](https://docs.hydrobit.ag/spec/openapi/production-records/checkidempotencykey.md): Checks if an idempotency key has been used before.

Requires JWT token authentication in the Authorization header.

Returns 200 if key exists, 404 if not.

### Get a production record

 - [GET /api/control/production/records/{recordId}](https://docs.hydrobit.ag/spec/openapi/production-records/getproductionrecord.md): Retrieves detailed information about a specific production record.

Requires JWT token authentication in the Authorization header.

### Void a production record

 - [POST /api/control/production/records/{recordId}/void](https://docs.hydrobit.ag/spec/openapi/production-records/voidproductionrecord.md): Voids (cancels) a production record by creating a counter-movement with negative units.

Requires JWT token authentication in the Authorization header.

Only the session owner can void records. Session must be open.
Supports idempotency - voiding the same record multiple times is safe.

## Phytosanitary

Endpoints for phytosanitary monitoring and analysis (pest/disease tracking)

### Get phytosanitary monitoring summary

 - [GET /api/control/phytosanitary/summary](https://docs.hydrobit.ag/spec/openapi/phytosanitary/getphytosanitarysummary.md): Retrieves aggregated phytosanitary data (pest and disease incidence/severity) for a specified time range.

Requires API token authentication with read:phytosanitary scope via the x-api-key header.

Key features:
- Aggregates data from phytosanitary form records
- Supports filtering by company, project, or sector
- Returns incidence and severity metrics per sector
- Maximum range: 180 days
- Dates must be in YYYY-MM-DD format (local time, no timezone suffix)
- Timezone is automatically resolved from the project settings

### Get phytosanitary summary for entire company

 - [GET /api/control/phytosanitary/company-summary](https://docs.hydrobit.ag/spec/openapi/phytosanitary/getphytosanitarycompanysummary.md): Retrieves aggregated phytosanitary data (pest and disease incidence/severity) for all projects and sectors belonging to the authenticated company within a specified time range.

Requires API token authentication with read:phytosanitary scope via the x-api-key header.

Key features:
- Automatically uses companyId from the authenticated API token
- Aggregates data from all projects and sectors belonging to the company
- Returns incidence and severity metrics grouped by project and sector
- Maximum range: 180 days
- Dates must be in YYYY-MM-DD format (local time, no timezone suffix)
- Timezone is automatically resolved from the company's projects
- No need to specify companyId, projectId, or sectorId manually

## Weather

Endpoints for weather and climate data retrieval

### Get weather time series for local range

 - [GET /api/iot/weather](https://docs.hydrobit.ag/spec/openapi/weather/getweatherseries.md): Returns weather and microclimate time series for a project within a local-time range (Leaf-style).
Auth via API token in x-api-key.

## Plant

Endpoints for plant monitoring, growth, and health data

### Get plant health and vigor series for local range

 - [GET /api/iot/plant](https://docs.hydrobit.ag/spec/openapi/plant/getplantseries.md): Returns plant KPIs (e.g., vigor, incidence, severity) aggregated for a project in a local-time range.
Auth via API token in x-api-key.

## Irrigation

Endpoints for irrigation control, logs, and automation

### Get irrigation events for local range

 - [GET /api/iot/irrigation](https://docs.hydrobit.ag/spec/openapi/irrigation/getirrigationevents.md): Returns irrigation events for a project within a local-time range.
Auth via API token in x-api-key.

## IoT Endpoint

Endpoints for IoT devices, telemetry, and field data integration

### Establish mqtt connection over websocket

 - [GET /mqtt](https://docs.hydrobit.ag/spec/openapi/iot-endpoint/mqttoverwebsocket.md): Upgrade to WebSocket at wss://iot.hydrobit.ag/mqtt and authenticate with x-iot-token.
After upgrade, speak MQTT (v3.1.1). Use deviceId to scope topics.