Skip to content

Hydrobit API (2.0.0)

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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://hydrobit.ag
Hydrobit Support
support@hydrobit.ag
License
Proprietary
Languages
Servers
Mock server
https://docs.hydrobit.ag/_mock/spec/openapi/
Production server
https://api.hydrobit.ag/
IoT server
https://iot.hydrobit.ag/
MQTT over WebSocket endpoint
wss://iot.hydrobit.ag/

Forms

Endpoints for form management and record submission

Operations

Projects

Endpoints for project and sector data retrieval

Operations

Workers

Endpoints for worker management and operations

Operations

Create a new worker

Request

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
Security
bearerAuth
Bodyapplication/jsonrequired
auth0Idstringrequired

User identifier (internal use, derived from JWT token)

Example: "user_123456789"
first_namestringrequired

Worker first name

Example: "John"
last_namestringrequired

Worker last name

Example: "Smith"
phonestring

Worker phone number

Example: "+1234567890"
emailstring

Worker email address

Example: "john.smith@example.com"
positionstringrequired

Worker position (must match template options)

Example: "field_worker"
employment_typestringrequired

Employment type (must match template options)

Example: "full_time"
hire_datestring(date)required

Hire date in YYYY-MM-DD format (used to generate worker_id)

Example: "2025-03-15"
termination_datestring or null(date)

Termination date in YYYY-MM-DD format (optional)

Example: null
statusstring

Worker status (defaults to 'active')

Example: "active"
hourly_ratenumber

Hourly rate (must be >= 0)

Example: 18.5
emergency_contact_namestring

Emergency contact name

Example: "Jane Smith"
emergency_contact_phonestring

Emergency contact phone number

Example: "+1234567891"
skillsArray of strings

Array of worker skills (filtered by template options)

Example: ["irrigation","pruning"]
notesstring

Additional notes about the worker

Example: "Experienced in avocado cultivation"
photostring

Worker photo in base64 data URL format (optional). Supported formats: JPEG, PNG, WebP. Maximum size: 12MB. Format: data:image/jpeg;base64,/9j/4AAQ... or data:image/png;base64,iVBORw0KG...

Example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
curl -i -X POST \
  https://docs.hydrobit.ag/_mock/spec/openapi/api/control/workers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auth0Id": "user_123456789",
    "first_name": "John",
    "last_name": "Smith",
    "hire_date": "2025-03-15",
    "position": "field_worker",
    "employment_type": "full_time"
  }'

Responses

Worker already exists (idempotent response)

Bodyapplication/json
statusstring
Example: "exists"
messagestring
Example: "worker already exists"
dataobject
Response
application/json
{
  "status": "exists",
  "message": "worker already exists",
  "data": {
    "workerId": "6507f1e3c9d8e2a4b1f9c3d5",
    "worker_id": "JS0315"
  }
}

Get list of workers

Request

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)
Security
bearerAuth
Query
auth0Idstringrequired

User identifier (internal use, can be derived from JWT token)

Example: auth0Id=user_123456789
companyIdstring

Company identifier (must match user's company, otherwise forbidden)

Example: companyId=comp_12345
qstring

Search query (searches in first_name, last_name, and worker_id)

Example: q=John
statusstring

Filter by worker status

Example: status=active
positionstring

Filter by worker position

Example: position=field_worker
employment_typestring

Filter by employment type

Example: employment_type=full_time
pageinteger>= 1

Page number (default 1)

Default 1
Example: page=1
limitinteger[ 1 .. 100 ]

Number of items per page (default 25, max 100)

Default 25
Example: limit=25
curl -i -X GET \
  'https://docs.hydrobit.ag/_mock/spec/openapi/api/control/workers?auth0Id=user_123456789&companyId=comp_12345&q=John&status=active&position=field_worker&employment_type=full_time&page=1&limit=25' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Workers retrieved successfully

Bodyapplication/json
statusstring
Example: "success"
dataobject
Response
application/json
{
  "status": "success",
  "data": {
    "total": 42,
    "page": 1,
    "pageSize": 25,
    "items": [ … ]
  }
}

Get a single worker

Request

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
Security
bearerAuth
Path
workerstringrequired

Worker identifier (unique id or worker_id like "JS0315")

Examples:
6507f1e3c9d8e2a4b1f9c3d5
JS0315
Query
auth0Idstringrequired

User identifier (internal use, can be derived from JWT token)

Example: auth0Id=user_123456789
curl -i -X GET \
  'https://docs.hydrobit.ag/_mock/spec/openapi/api/control/workers/{worker}?auth0Id=user_123456789' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Worker retrieved successfully

Bodyapplication/json
statusstring
Example: "success"
dataobject
Response
application/json
{
  "status": "success",
  "data": {
    "_id": "6507f1e3c9d8e2a4b1f9c3d5",
    "worker_id": "JS0315",
    "first_name": "John",
    "last_name": "Smith",
    "name": "John Smith",
    "phone": "+1234567890",
    "email": "john.smith@example.com",
    "position": "field_worker",
    "employment_type": "full_time",
    "hire_date": "2025-03-15",
    "termination_date": null,
    "status": "active",
    "hourly_rate": 18.5,
    "emergency_contact_name": "Jane Smith",
    "emergency_contact_phone": "+1234567891",
    "skills": [ … ],
    "notes": "Experienced in avocado cultivation",
    "photo": "https://storage.example.com/photos/worker-photo.jpg",
    "companyId": "comp_12345",
    "companyName": "Hydrobit Client SA",
    "createdAt": "2025-03-15T10:30:00.000Z",
    "updatedAt": "2025-03-15T10:30:00.000Z"
  }
}

Production Sessions

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

Operations

Production Records

Endpoints for creating and managing production records

Operations

Phytosanitary

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

Operations

Weather

Endpoints for weather and climate data retrieval

Operations

Plant

Endpoints for plant monitoring, growth, and health data

Operations

Irrigation

Endpoints for irrigation control, logs, and automation

Operations

IoT Endpoint

Endpoints for IoT devices, telemetry, and field data integration

Operations