Maintenance API — VenHub Developer Docs

POST /maintenance/reports

Create a new maintenance report with optional media attachments.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/maintenance/reports

Auth API Key or Firebase

Required Scope maintenance:write

Content-Type multipart/form-data

ℹ️

This endpoint uses multipart/form-data instead of application/json. The formData field must be a JSON-encoded string.

Example Request

cURL

curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/maintenance/reports" \
  --header "X-API-Key: vh_abc123..." \
  --form 'formData={"serviceType":"Corrective","hubId":123,"name":"Bin 2 motor swap","submittedBy":"[email protected]","serviceStartTime":"2026-02-05T13:00:00Z","timestamp":"2026-02-05T14:30:00Z","description":"Replaced motor"}' \
  --form '[email protected]'

Parameters

Parameter	Type	Required	Description
`formData`	JSON String	Required	Maintenance report data (JSON-encoded string)
`media`	File[]	Optional	Media files (images/videos) to attach to the report

formData Fields

Field	Type	Required	Description
`hubId`	Integer	Required	Hub ID being serviced
`name`	String	Required	Short title for the report
`submittedBy`	String	Required	Identifier (e.g. email) of the person filing the report
`serviceType`	String	Required	Free text describing the type of maintenance performed. `"Corrective"`/`"Preventive"` are common values, not enforced by the API.
`serviceStartTime`	ISO 8601	Required	Service start time (e.g. `"2026-02-05T13:00:00Z"`)
`timestamp`	ISO 8601	Required	Report submission timestamp
`hubTested`	String	Optional	Whether the hub was tested after service (e.g. `"Yes, it is working."`)
`serviceEndTime`	ISO 8601	Optional	Service end time (e.g. `"2026-02-05T14:30:00Z"`)
`description`	String	Optional	Additional notes about the service performed
`componentsServiced`	String[]	Optional	List of components serviced (e.g. `["delivery_bin_2", "motor"]`)

Response

JSON — 200 OK

{
  "success": true,
  "message": "Maintenance report created successfully",
  "report": {
    "id": 45,
    "hub_id": 123,
    "service_type": "Corrective",
    "created_at": "2026-02-05T14:30:00Z",
    "media_assets": [
      {
        "original_name": "photo1.jpg",
        "bucket_uri": "https://storage.example.com/maintenance/photo1.jpg",
        "mime_type": "image/jpeg",
        "size": 204800,
        "fieldname": "media"
      }
    ]
  }
}

Errors

Error Code	Description
hub_id_required	The `hubId` field is missing from the `formData` JSON
invalid_json	The `formData` field could not be parsed as valid JSON
unauthorized	API key does not have access to the specified hub or lacks the required scope

GET /maintenance/reports

Get paginated list of maintenance reports with optional hub filter.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/maintenance/reports

Auth API Key or Firebase

Required Scope maintenance:read

Example Request

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/maintenance/reports?hub_id=123&page=1&per_page=20" \
  --header "X-API-Key: vh_abc123..."

Parameters

Parameter	Type	Required	Default	Description
`hub_id`	String	Optional	`null`	Filter results by hub ID
`page`	Integer	Optional	`1`	Page number
`per_page`	Integer	Optional	`20`	Items per page (1–100)

Response

JSON — 200 OK

{
  "logs": [
    {
      "id": 45,
      "hub_id": 123,
      "service_type": "Corrective",
      "hub_tested": "Yes, it is working.",
      "service_start_time": "2026-02-05T13:00:00Z",
      "service_end_time": "2026-02-05T14:30:00Z",
      "description": "Replaced motor",
      "components_serviced": ["delivery_bin_2", "motor"],
      "media_assets": [{ "original_name": "photo1.jpg", "bucket_uri": "https://storage.example.com/maintenance/photo1.jpg", "mime_type": "image/jpeg", "size": 204800, "fieldname": "media" }],
      "submitted_by": "[email protected]",
      "created_at": "2026-02-05T14:30:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}

GET /maintenance/reports/{log_id}

Get detailed information for a specific maintenance report.

Version 1

URL https://tina-api.venhub.com/api/v1/owners/maintenance/reports/{log_id}

Auth API Key or Firebase

Required Scope maintenance:read

Example Request

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/maintenance/reports/45" \
  --header "X-API-Key: vh_abc123..."

Parameters

Parameter	Type	Location	Required	Description
`log_id`	Integer	Path	Required	Maintenance report ID

Response

JSON — 200 OK

{
  "id": 45,
  "hub_id": 123,
  "service_type": "Corrective",
  "hub_tested": "Yes, it is working.",
  "service_start_time": "2026-02-05T13:00:00Z",
  "service_end_time": "2026-02-05T14:30:00Z",
  "description": "Replaced motor on bin 2",
  "components_serviced": [
    "delivery_bin_2",
    "motor"
  ],
  "media_assets": [
    {
      "original_name": "photo1.jpg",
      "bucket_uri": "https://storage.example.com/maintenance/photo1.jpg",
      "mime_type": "image/jpeg",
      "size": 204800,
      "fieldname": "media"
    }
  ],
  "submitted_by": "[email protected]",
  "created_at": "2026-02-05T14:30:00Z"
}

Errors

Error Code	Description
not_found	No maintenance report exists with the specified ID, or you do not have access to it
unauthorized	API key does not have the required scope or lacks access to the associated hub