openapi: 3.0.3 info: license: name: Proprietary url: https://www.hiboo.io/ title: Hiboo API description: | The all-in-one Mixed Fleet API for your equipment data, operations, and maintenance. ## Authenticating requests 1. Call `POST /login` with the `name` and `apiKey` of your API credential. The response contains a `token`. 2. Send this token with every other request, in the `x-access-token` header. The `Authorization: Bearer ` header also works. 3. A token is valid for 10 days. When a request returns `401`, call `POST /login` again to get a new token. The [Authenticate & Test guide](https://docs.hiboo.io/guides/getting-started/authenticate-test) shows a first call step by step. contact: name: Hiboo Support email: support@hiboo.io url: https://www.hiboo.io/ version: 2.0.0 x-logo: url: https://app.hiboo.io/images/logo.png backgroundColor: '#FAFAFA' altText: Hiboo logo servers: - url: https://api.hiboo.io description: Production server - url: https://api-sandbox.hiboo.io description: Sandbox server tags: - name: Login description: Exchange the name and API key of your API credential for a token, valid for 10 days. Send this token with every other request, in the `x-access-token` header. - name: Mixed Fleet Data description: The following endpoints allow you to retrieve all your Mixed Fleet Data such as positions, daily usages, fault codes, and more. - name: Snapshot description: The following endpoints allow you to retrieve the last information available for all data kinds for a specific equipment or the entire fleet. x-parent: Mixed Fleet Data - name: Time Series description: The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine. x-parent: Mixed Fleet Data - name: Fleet Identity description: Manage your fleet identity, including equipments, workspaces, and custom fields. - name: Fleet description: The following endpoints allow you to retrieve the list of all equipments and manage their identity. x-parent: Fleet Identity - name: Workspaces description: The following endpoints allow you to retrieve the list of all workspaces available and manage the link between equipments and workspaces. x-parent: Fleet Identity - name: Equipment Identity description: The following endpoints allow you to manage the identity of your equipments, such as enterprise, year, model, and custom fields. x-parent: Fleet Identity - name: Equipment Documents description: The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents. x-parent: Fleet Identity - name: Equipment Groups description: The following endpoints allow you to manage equipment groups, enabling you to link multiple equipments together. x-parent: Fleet Identity - name: Hiboo Connect description: The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process. - name: Contracts description: The following endpoints allow you to assign your equipments to contracts data, so that Hiboo can detect out-of-contract usages. - name: Catalog description: The following endpoints allow you to retrieve the data sources, and connect and manage the integrations, including via OAuth. - name: Integrations description: The following endpoints allow you to retrieve the data sources, and create and manage the integrations. x-parent: Catalog - name: OAuth description: The following endpoints allow you to connect data sources that require the user to log in on their own portal. See the [OAuth guide](https://docs.hiboo.io/guides/guides/managing-your-fleet/connecting-oauth-data-sources). x-parent: Catalog x-tagGroups: - name: Authentication tags: - Login - name: Mixed Fleet Data tags: - Snapshot - Time Series - name: Fleet Identity tags: - Fleet - Workspaces - Equipment Identity - Equipment Documents - Equipment Groups - name: Hiboo Connect tags: - Hiboo Connect - name: Contracts tags: - Contracts - name: Catalog tags: - Integrations - OAuth security: - JWT: [] components: securitySchemes: JWT: type: apiKey in: header name: x-access-token description: | Token returned by `POST /login`: a JWT, valid for 10 days. Send it in the `x-access-token` header, as `x-access-token: `. The `Authorization: Bearer ` header also works. When a request returns `401`, call `POST /login` again. schemas: NoDetailError: required: - message type: object properties: message: type: string description: A human readable description of the error ValidationErrorDetail: required: - field - code - message type: object properties: field: type: string description: Dot-separated path of the invalid field (e.g. `properties.customer`), or an empty string when the whole body is invalid code: type: string description: | Machine-readable reason of the error: - INVALID_TYPE: missing field, or wrong type (e.g. a string instead of a number). - INVALID_FORMAT: wrong string format (email, date-time, date) - INVALID_VALUE: value not in the allowed list - TOO_SMALL: below the minimum (length, number of items, value) - TOO_BIG: above the maximum - UNKNOWN_FIELD: field not accepted - INVALID: other validation rule enum: - INVALID_TYPE - INVALID_FORMAT - INVALID_VALUE - TOO_SMALL - TOO_BIG - UNKNOWN_FIELD - INVALID message: type: string description: A human readable description of the error. It may change at any time, use `code` instead ValidationError: required: - message - code - details type: object properties: message: type: string description: A human readable description of the error. It may change at any time, use `code` instead code: type: string enum: - INVALID_PARAMETERS details: type: array description: One entry per invalid field. If the type of a field is wrong, only its INVALID_TYPE error is returned items: $ref: '#/components/schemas/ValidationErrorDetail' asset: type: object properties: assetId: type: number serialNumber: type: string make: type: string name: type: string category: type: string description: The category must exist beforehand and will not be created if it does not exist model: type: string entreprise: type: string year: oneOf: - type: number Error: required: - message - details type: object properties: message: type: string description: A human readable description of the error details: type: object description: Additional information about the Error bodyAssetWorkspaceNames: type: object properties: assetId: type: number serialNumber: type: string make: type: string workspaceNames: type: array items: type: string bodyAssetCustomFields: type: object properties: assetId: type: number serialNumber: type: string make: type: string customFields: type: array items: type: object properties: label: type: string value: type: string required: - label - value Document: required: - id - name - shareable - isPublic - expirationDate - uploadDate - fileInfos type: object properties: id: type: number description: The unique identifier of the document name: type: string description: The name of the document shareable: type: boolean description: Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private. isPublic: type: boolean description: Indicates whether the document can be publicly accessible. expirationDate: type: string description: Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC. format: date pattern: /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/ fileInfos: type: object description: Metadata about the file properties: size: type: number description: The size of the file in kB (e.g., 2 for a 2kB file). example: 3.56 contentType: type: string description: The MIME type of the file (e.g., `application/pdf`, `image/jpeg`, `image/png`). example: application/pdf uploadDate: type: string description: The date and time when the document was uploaded, serialized as an ISO 8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). format: date-time UploadDocumentBody: required: - file - name type: object properties: name: type: string description: The name of the document. file: type: string format: binary description: The document file to be uploaded. The document must be one of the following types PDF, JPEG, PNG, GIF, TIFF, Excel, or Word documents. File size should not exceed 10MB (10,485,760 bytes). shareable: type: boolean description: Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private. default: false isPublic: type: boolean description: Indicates whether the document can be publicly accessible. default: false expirationDate: type: string description: Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC. format: date pattern: /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/ PatchDocumentBody: type: object properties: name: type: string description: The name of the document. expirationDate: type: string description: Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC. format: date pattern: /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/ CreateGroupBody: required: - assetIds type: object properties: assetIds: type: array description: List of equipment IDs to group together. At least 2 equipment IDs are required. minItems: 2 items: type: integer example: - 1 - 2 - 3 GroupBodySerialized: required: - id - assetIds type: object properties: id: type: integer description: The unique identifier of the group example: 42 assetIds: type: array description: List of equipment IDs in the group items: type: integer example: - 1 - 2 - 3 Sharing: required: - reference - startDate - dataPacksCodes - assetIds - recipient - notificationEnabled - properties type: object properties: reference: type: string description: It can be a contract reference for instance example: contract-4242-2024 startDate: description: Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). type: string format: date-time example: '2030-01-01T08:00:00Z' endDate: description: Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure type: string format: date-time example: '2030-12-31T18:00:00Z' status: description: | Current status of the sharing: - pending: The beneficiary user has not yet created an organization in Hiboo - planned: The sharing will be active ("in progress" status) as soon as the start date is reached - in_progress: The sharing is in progress and the beneficiary users have access to the assets data stream - stopped: The sharing has been stopped before the initially scheduled end date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history - completed: The sharing has ended on the scheduled date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history type: string enum: - pending - planned - in_progress - stopped - completed dataPacksCodes: description: List of data packs shared type: array minItems: 0 items: type: string enum: - essential - vehicle_conditions - energy_and_fuel - activity - others - usage_hours - fault_codes example: - essential - vehicle_conditions - energy_and_fuel - activity - others - usage_hours - fault_codes assetIds: description: All the equipment that you wish to share, use Hiboo's ids type: array minItems: 1 items: type: number format: int32 example: - 1 - 2 - 3 recipient: description: Recipient's email address type: string format: email example: john.doe@example.com notificationEnabled: description: Defines if the notification is enabled on the sharing creation/start actions type: boolean properties: type: object description: Additional properties of the sharing properties: customer: type: string description: Customer name example: Customer Name site: type: string description: Site name example: Site Name contract: type: string description: Contract reference example: XK-123456 purchaseOrder: type: string description: Purchase order reference example: 0986-XX-60 project: type: string description: Project reference example: ABC-123-ZX-456 accountNumber: type: string description: Account number example: '1234' CreateSharingBody: required: - reference - startDate - endDate - assetIds - recipient type: object properties: reference: type: string description: It can be a contract reference for instance example: contract-4242-2024 startDate: description: Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). The date must not be before one rolling year. type: string format: date-time example: '2030-01-01T08:00:00Z' endDate: description: Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, set it to `null` if the end date is unsure. When set, it must be at least 1 hour after the start date. type: string format: date-time example: '2030-12-31T18:00:00Z' optionalDataPackCodes: deprecated: true description: '**Deprecated.** Use `excludedDataPackCodes` instead. An optional list of data packs to share. If not specified, all data will be shared by default. If set to an empty list, only base data will be shared. Otherwise, base data and specified optional data packs will be shared. If both `optionalDataPackCodes` and `excludedDataPackCodes` are provided, `excludedDataPackCodes` will take precedence and `optionalDataPackCodes` will be ignored. idle data pack is always provided when passing optionalDataPackCodes, even if not specified, to avoid retrocompability issues. To exclude it, use excludedDataPackCodes parameter instead.' type: array minItems: 0 items: type: string enum: - fault_codes example: fault_codes excludedDataPackCodes: description: An optional list of data packs to exclude from sharing. If not specified, all data will be shared by default. If set to an empty list, no data pack will be excluded. Otherwise, specified data packs will be excluded from sharing. type: array minItems: 0 items: type: string enum: - fault_codes - idle example: fault_codes assetIds: description: All the equipment that you wish to share, use Hiboo's ids type: array minItems: 1 items: type: number format: int32 example: 1 recipient: description: Recipient's email address. The local part of the email address can only contain alphanumeric characters and the characters _ ' + - and . type: string format: email example: john.doe@example.com notificationEnabled: description: If false, the recipient will not be notified when the sharing is created or started type: boolean properties: type: object description: Additional properties to be added to the sharing properties: customer: type: string description: Customer name example: Customer Name site: type: string description: Site name example: Site Name contract: type: string description: Contract reference example: XK-123456 purchaseOrder: type: string description: Purchase order reference example: 0986-XX-60 project: type: string description: Project reference example: ABC-123-ZX-456 accountNumber: type: string description: Account number example: '1234' PatchSharingBody: type: object properties: reference: type: string description: It can be a contract reference for instance example: contract-4242-2024 startDate: description: Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). The date must not be before one rolling year. type: string format: date-time example: '2030-01-01T08:00:00Z' endDate: description: Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure. When set, the resulting sharing (after merging with the existing dates) must last at least 1 hour. type: string format: date-time example: '2030-12-31T18:00:00Z' optionalDataPackCodes: deprecated: true description: '**Deprecated.** Use `excludedDataPackCodes` instead. An optional list of data packs to share. If not specified, all data will be shared by default. If set to an empty list, only base data will be shared. Otherwise, base data and specified optional data packs will be shared. If both `optionalDataPackCodes` and `excludedDataPackCodes` are provided, `excludedDataPackCodes` will take precedence and `optionalDataPackCodes` will be ignored. idle data pack is always provided when passing optionalDataPackCodes, even if not specified, to avoid retrocompability issues. To exclude it, use excludedDataPackCodes parameter instead.' type: array minItems: 0 items: type: string enum: - fault_codes example: fault_codes excludedDataPackCodes: description: An optional list of data packs to exclude from sharing. If not specified, all data will be shared by default. If set to an empty list, no data pack will be excluded. Otherwise, specified data packs will be excluded from sharing. type: array minItems: 0 items: type: string enum: - fault_codes - idle example: fault_codes properties: type: object description: Additional properties about the sharing properties: customer: type: string description: Customer name example: Customer Name site: type: string description: Site name example: Site Name contract: type: string description: Contract reference example: XK-123456 purchaseOrder: type: string description: Purchase order reference example: 0986-XX-60 project: type: string description: Project reference example: ABC-123-ZX-456 accountNumber: type: string description: Account number example: '1234' ContractAssignment: required: - id - contractReference - assetId - startDate - endDate - maximumHoursPerDay - customer - workingDays - excludedDays - includedDays - excludePublicHolidays - country - dailyRate - currency type: object properties: id: description: Unique identifier of the contract assignment, generated by Hiboo type: integer format: int32 example: 42 contractReference: description: The reference of the contract the equipment is assigned to type: string example: XK-123456 assetId: description: Hiboo's id of the equipment assigned to the contract type: integer format: int32 example: 1 startDate: description: First day of the contract assignment (YYYY-MM-DD), asset timezone type: string format: date example: '2026-01-01' endDate: description: Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date type: string format: date example: '2026-12-31' maximumHoursPerDay: description: Maximum number of usage hours per day allowed by the contract. `null` if the contract does not limit the daily usage type: number nullable: true example: 8 customer: description: Name of the customer renting the equipment type: string example: Customer Name workingDays: description: Days of the week on which the equipment is expected to be used under the contract type: array minItems: 1 items: type: string enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday example: - monday - tuesday - wednesday - thursday - friday excludedDays: description: Specific dates (YYYY-MM-DD) excluded from the contract, even if they fall on a working day type: array items: type: string format: date example: - '2026-08-15' includedDays: description: Specific dates (YYYY-MM-DD) included in the contract, even if they do not fall on a working day type: array items: type: string format: date example: - '2026-06-06' excludePublicHolidays: description: If true, public holidays of the specified country are excluded from the contract type: boolean country: description: Country used to determine public holidays type: string enum: - FR - GB example: FR dailyRate: description: Daily rate charged for out-of-contract usage. `null` if not defined type: number nullable: true example: 350 currency: description: Currency of the daily rate, as a 3-letter ISO 4217 code type: string minLength: 3 maxLength: 3 example: EUR CreateContractAssignmentBody: required: - contractReference - assetId - startDate - endDate - customer - workingDays - country - currency type: object properties: contractReference: description: The reference of the contract the equipment is assigned to type: string minLength: 1 example: XK-123456 assetId: description: Hiboo's id of the equipment to assign to the contract type: integer format: int32 example: 1 startDate: description: First day of the contract assignment (YYYY-MM-DD), asset timezone type: string format: date example: '2026-01-01' endDate: description: Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date type: string format: date example: '2026-12-31' maximumHoursPerDay: description: Maximum number of usage hours per day allowed by the contract, between 0 (exclusive) and 24. Set it to `null` or omit it if the contract does not limit the daily usage type: number nullable: true exclusiveMinimum: true minimum: 0 maximum: 24 example: 8 customer: description: Name of the customer renting the equipment type: string minLength: 1 example: Customer Name workingDays: description: Days of the week on which the equipment is expected to be used under the contract type: array minItems: 1 items: type: string enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday example: - monday - tuesday - wednesday - thursday - friday excludedDays: description: Specific dates (YYYY-MM-DD) to exclude from the contract, even if they fall on a working day. A date cannot be both excluded and included type: array items: type: string format: date example: - '2026-08-15' includedDays: description: Specific dates (YYYY-MM-DD) to include in the contract, even if they do not fall on a working day. A date cannot be both excluded and included type: array items: type: string format: date example: - '2026-06-06' excludePublicHolidays: description: If true, public holidays of the specified country are excluded from the contract. Defaults to false type: boolean country: description: Country used to determine public holidays type: string enum: - FR - GB example: FR dailyRate: description: Daily rate charged for out-of-contract usage. Must be greater than or equal to 0. Set it to `null` or omit it if not defined type: number nullable: true minimum: 0 example: 350 currency: description: Currency of the daily rate, as a 3-letter ISO 4217 code type: string minLength: 3 maxLength: 3 example: EUR EditContractAssignmentBody: required: - startDate - endDate - customer - workingDays - country - currency type: object properties: startDate: description: First day of the contract assignment (YYYY-MM-DD), asset timezone type: string format: date example: '2026-01-01' endDate: description: Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date type: string format: date example: '2026-12-31' maximumHoursPerDay: description: Maximum number of usage hours per day allowed by the contract, between 0 (exclusive) and 24. Set it to `null` or omit it if the contract does not limit the daily usage type: number nullable: true exclusiveMinimum: true minimum: 0 maximum: 24 example: 8 customer: description: Name of the customer renting the equipment type: string minLength: 1 example: Customer Name workingDays: description: Days of the week on which the equipment is expected to be used under the contract type: array minItems: 1 items: type: string enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday example: - monday - tuesday - wednesday - thursday - friday excludedDays: description: Specific dates (YYYY-MM-DD) to exclude from the contract, even if they fall on a working day. A date cannot be both excluded and included type: array items: type: string format: date example: - '2026-08-15' includedDays: description: Specific dates (YYYY-MM-DD) to include in the contract, even if they do not fall on a working day. A date cannot be both excluded and included type: array items: type: string format: date example: - '2026-06-06' excludePublicHolidays: description: If true, public holidays of the specified country are excluded from the contract. Defaults to false type: boolean country: description: Country used to determine public holidays type: string enum: - FR - GB example: FR dailyRate: description: Daily rate charged for out-of-contract usage. Must be greater than or equal to 0. Set it to `null` or omit it if not defined type: number nullable: true minimum: 0 example: 350 currency: description: Currency of the daily rate, as a 3-letter ISO 4217 code type: string minLength: 3 maxLength: 3 example: EUR CredentialField: type: object required: - name - type - required properties: name: description: Key of the field in the integration credentials type: string example: clientId type: description: JSON type of the field value. A list when the field accepts several types. oneOf: - type: string enum: - string - number - boolean - type: array items: type: string enum: - string - number - boolean example: string required: description: Whether the field must be sent. When false, the field can be left out. type: boolean example: true value: description: Values accepted for this field. A single value means the field is constant; constant fields come first and tell which variant the credentials use. type: array items: oneOf: - type: string - type: number - type: boolean example: - client_credentials - password CredentialsSchema: description: Credentials accepted by the data source. Send the fields of exactly one variant. type: object nullable: true required: - variants properties: variants: type: array items: type: object required: - fields properties: fields: type: array items: $ref: '#/components/schemas/CredentialField' example: variants: - fields: - name: authenticationMethod type: string value: - subscription_key required: false - name: subscriptionKeyPrimary type: string required: true - name: subscriptionKeySecondary type: string required: true - fields: - name: authenticationMethod type: string value: - oauth_client_credentials required: true - name: clientId type: string required: true - name: clientSecret type: string required: true GetIntegrationResponse: type: object properties: id: description: The unique identifier of the integration type: number example: 123 name: description: Name of the integration type: string example: MCF France dataSourceCode: description: Code of the data source type: string example: michelin_connected_fleet status: description: | Health state of the integration: - `INACTIVE`: integration is deactivated - `INITIAL_RUN`: first data retrieval in progress - `DATA_FLOWING`: data is received - `DATA_PARTIALLY_FLOWING`: data is received, with recurrent errors - `DATA_NOT_FLOWING`: no data is received (e.g. invalid credentials, provider API down) type: string enum: - INACTIVE - INITIAL_RUN - DATA_FLOWING - DATA_PARTIALLY_FLOWING - DATA_NOT_FLOWING example: DATA_FLOWING CreateIntegrationBody: required: - integrationCredentials - integrationName - dataSourceCode type: object properties: integrationCredentials: type: object description: The credentials to connect to the data source, the content of this object will depend on the data source you want to connect to. example: username: user password: pass customerId: '123' integrationName: description: Name of the integration type: string example: MCF France dataSourceCode: description: Code of the data source type: string example: michelin_connected_fleet IntegrationIdResponse: type: object properties: integrationId: description: The unique identifier of the created integration type: number example: 123 PatchIntegrationBody: required: - integrationName type: object properties: integrationCredentials: type: object description: The new credentials to connect to the data source, the content of this object will depend on the data source you want to connect to. example: username: user password: pass customerId: '123' integrationName: description: The new name of the integration type: string example: MCF France PatchIntegrationResponse: type: object properties: integrationId: description: The unique identifier of the updated integration type: number example: 123 integrationName: description: Name of the updated integration type: string example: MCF France InitOAuthSessionBody: required: - dataSourceCode - integrationName - integrationCredentials - redirectUri type: object properties: dataSourceCode: description: Code of an OAuth data source type: string enum: - johndeere_aemp_2_0 - johndeere_operations - case_aemp_2 - wacker_neuson_aemp_2 example: wacker_neuson_aemp_2 integrationName: description: Name of the integration type: string example: Wacker Neuson - Main fleet integrationCredentials: type: object description: Supplementary credentials required by the data source. `{}` if none. Wacker Neuson requires `clientId` and `clientSecret`. example: clientId: your-client-id clientSecret: your-client-secret redirectUri: description: URL where the user's browser is redirected once the flow completes, success or failure type: string format: uri example: https://app.example.com/integrations/oauth/callback OAuthSessionResponse: type: object properties: oauthUrl: description: Data source login and consent page to open in the user's browser type: string example: https://signin.johndeere.com/oauth2/.../v1/authorize?client_id=...&state=... sessionId: description: Identifier of the OAuth session, valid for 15 minutes type: string example: b3f1c2a4-5d6e-4f70-8a9b-0c1d2e3f4a5b OAuthSessionResult: oneOf: - type: object required: - status - integrationId properties: status: type: string enum: - completed integrationId: description: The unique identifier of the created or re-authenticated integration type: number example: 123 - type: object required: - status - reason properties: status: type: string enum: - error reason: description: Failure reason type: string example: 'Failed to authenticate with John Deere: invalid_grant' OAuthRedirectBody: required: - redirectUri type: object properties: redirectUri: description: URL where the user's browser is redirected once the flow completes, success or failure type: string format: uri example: https://app.example.com/integrations/oauth/callback SetupLinksResponse: type: object properties: links: description: Data source pages where the user completes the setup. Empty when the data source has none. type: array items: type: object properties: code: description: | Link identifier. John Deere returns: - `select-organizations`: choose the organizations shared with Hiboo - `manage-connections`: manage the connection to Hiboo type: string example: select-organizations url: description: Page to open in the user's browser type: string example: https://connections.deere.com/connections/.../select-organizations?redirect_uri=... parameters: limit: name: limit in: query description: The numbers of items to return required: false schema: type: integer format: int32 default: 20 maximum: 50 offset: name: offset in: query description: The number of items to skip before starting to collect the result set required: false schema: type: integer format: int32 default: 0 FilterByInProgressSharing: name: filterByInProgressSharing in: query description: This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not. required: false schema: type: integer examples: '0': value: 0 summary: Filter by not in progress sharing '1': value: 1 summary: Filter by in progress sharing assetId: name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 since: name: since in: query required: false description: Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is beginning of yesterday UTC until: name: until in: query required: false description: Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is end of today UTC includeCustomFields: name: includeCustomFields in: query description: By default, customFields are not included. If set to one, the custom fields will be included in the response required: false schema: type: integer format: int32 default: 0 includeDataSources: name: includeDataSources in: query description: By default, data sources related to the equipment are not included. If set to one, the data sources will be included in the response required: false schema: type: integer format: int32 default: 0 includeGroup: name: includeGroup in: query description: By default, equipment group information is not included. If set to one, the group information will be included in the response required: false schema: type: integer format: int32 default: 0 responses: '201': description: Group successfully created content: application/json: schema: $ref: '#/components/schemas/GroupBodySerialized' '400': description: Invalid parameters. A group needs at least 2 equipments; when `assetIds` contains fewer than 2 IDs, `details` contains an entry with `field` `assetIds` and `code` `TOO_SMALL`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: message: Invalid parameters code: INVALID_PARAMETERS details: - field: assetIds code: TOO_SMALL message: 'Too small: expected array to have >=2 items' '403': description: Insufficient permissions to create a group with these equipments content: application/json: schema: $ref: '#/components/schemas/NoDetailError' '409': description: One or more equipments are already part of a group content: application/json: schema: $ref: '#/components/schemas/Error' SnapshotOfAllEquipments: description: Snapshot of all devices content: application/json: schema: type: object properties: data: type: object properties: total: type: integer format: int64 example: 1 rows: type: array items: type: object properties: id: type: integer example: 1 name: type: string example: D8000-1 make: type: string example: Caterpillar model: type: string example: '8000' serialNumber: type: string example: YVR001988 pin: type: string nullable: true description: Product Identification Number example: '12345678901234567' vin: type: string nullable: true description: Vehicle Identification Number example: 1HGBH41JXMN109186 cumulativeDistance: type: object properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string odometer: example: 54.2 format: float nullable: true type: number cumulativeFuelUsed: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true fuelUsed: type: number format: float example: 9520.5 fuelRemaining: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true percent: type: number format: float example: 65.5 cumulativeOperatingHours: type: object properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string hour: example: 1.5 format: float nullable: true type: number usageHours: example: 1.5 description: deprecated, is the same as hour. format: float nullable: true type: number lastPosition: type: object properties: date: type: string format: date-time description: Date of the last position example: '2019-11-06T00:00:00Z' latitude: type: number format: float example: 48.858269 longitude: type: number format: float example: 2.29447 altitude: type: number format: float nullable: true description: Altitude in meters above sea level example: 35 speed: type: number format: float nullable: true description: Speed in kilometers per hour example: 25.5 heading: type: number format: float nullable: true description: Heading/direction in degrees (0-360) example: 125.3 postalAddress: type: string nullable: true description: Reverse geocoded address of the last position. Null when no address could be resolved for these coordinates. example: 5 Avenue Anatole France, 75007 Paris, France cumulativeLoadCount: type: object nullable: true properties: count: type: integer format: int64 example: 1 date: type: string format: date-time example: '2019-11-06T00:00:00Z' cumulativePayloadTotal: type: object nullable: true properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' payload: type: integer format: int64 example: 1 cumulativeActiveRegenerationHours: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string hours: example: 15 format: int64 nullable: true type: integer cumulativePowerTakeOffHours: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string hours: example: 12 format: int64 nullable: true type: integer peakDailySpeed: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string speed: example: 100.5 format: float nullable: true type: number averageDailyEngineLoadFactor: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 88.24 DEFRemainingRatio: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 58.24 cumulativeIdleHours: type: object nullable: true properties: date: type: string format: date-time hours: example: 12 format: int64 nullable: true type: integer 401Error: description: Unable to authenticate the token content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Invalid token EquipmentsISO15143: description: ISO 15143-3 Fleet Snapshot Response content: application/json: schema: type: object required: - Equipment - Links - snapshotTime - version properties: Equipment: type: array items: type: object properties: EquipmentHeader: type: object required: - SerialNumber properties: UnitInstallDateTime: type: string nullable: true format: date-time example: '2024-01-15T10:30:00Z' OEMName: type: string example: Caterpillar Model: type: string example: 320D EquipmentID: type: string nullable: true example: EX001 SerialNumber: type: string example: ABC123456 PIN: type: string nullable: true example: '12345678901234567' VIN: type: string nullable: true example: 1HGBH41JXMN109186 HibooID: type: string example: '123' AverageLoadFactorLast24: type: object nullable: true properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Percent: type: number example: 75.5 Location: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Latitude: type: number example: 45.424721 Longitude: type: number example: -75.695 Altitude: type: number example: 100.5 AltitudeUnits: type: string example: metre CumulativeActiveRegenerationHours: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Hour: type: number example: 1250.5 CumulativeIdleHours: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Hour: type: number example: 500.25 CumulativeIdleNonOperatingHours: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Hour: type: number example: 500.25 CumulativeLoadCount: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Count: type: number example: 1250 CumulativeOperatingHours: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Hour: type: number example: 2500.75 CumulativePowerTakeOffHours: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Hour: type: number example: 150.5 CumulativePayloadTotals: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' PayloadUnits: type: string example: kilogram Payload: type: number example: 15000.5 DEFRemaining: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Percent: type: number example: 85.2 DEFTankCapacityUnits: type: string example: litre DEFTankCapacity: type: number example: 50 Distance: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' OdometerUnits: type: string example: kilometre Odometer: type: number example: 125000.5 EngineStatus: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' EngineNumber: type: string nullable: true example: ENG001 Running: type: boolean example: true FuelUsed: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' FuelUnits: type: string example: litre FuelConsumed: type: number example: 15000.25 FuelUsedLast24: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' FuelUnits: type: string example: litre FuelConsumed: type: number example: 125.5 FuelRemaining: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' Percent: type: number example: 65.8 FuelTankCapacityUnits: type: string example: litre FuelTankCapacity: type: number example: 500 MaximumSpeedLast24: type: object properties: datetime: type: string format: date-time example: '2024-01-15T10:30:00Z' SpeedUnits: type: string example: kilometres per hour Speed: type: number example: 45.5 Links: type: array items: type: object required: - rel - href properties: rel: type: string enum: - self - prev - next - last example: self href: type: string format: uri example: https://api.example.com/v2/iso15143-3/Fleet/1 snapshotTime: type: string format: date-time example: '2024-01-15T10:30:00Z' version: type: number example: 1 SnapshotOfSpecificEquipment: description: Latest snapshot of the machine content: application/json: schema: description: Snapshot of the specified device for all kinds properties: data: type: object properties: id: type: integer format: int32 example: 1 name: type: string example: CAT - 5 make: type: string example: Caterpillar model: type: string example: 816K serialNumber: type: string example: XICWITIDLXSX pin: type: string nullable: true description: Product Identification Number example: '12345678901234567' vin: type: string nullable: true description: Vehicle Identification Number example: 1HGBH41JXMN109186 lastPosition: type: object properties: date: type: string format: date-time description: Date of the last position example: '2019-11-06T00:00:00Z' latitude: type: number format: float example: 48.858269 longitude: type: number format: float example: 2.29447 altitude: type: number format: float nullable: true description: Altitude in meters above sea level example: 35 speed: type: number format: float nullable: true description: Speed in kilometers per hour example: 25.5 heading: type: number format: float nullable: true description: Heading/direction in degrees (0-360) example: 125.3 postalAddress: type: string nullable: true description: Reverse geocoded address of the last position. Null when no address could be resolved for these coordinates. example: 5 Avenue Anatole France, 75007 Paris, France cumulativeOperatingHours: type: object properties: date: type: string format: date-time description: Date of the last position example: '2019-11-06T00:00:00Z' nullable: true hour: nullable: true type: number format: float example: 1.5 cumulativeDistance: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true odometer: nullable: true type: number format: float example: 54.2 unit: type: string example: km cumulativeFuelUsed: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true fuelUsed: type: number format: float example: 9520.5 unit: type: string example: L cumulativeLoadCount: type: object nullable: true properties: count: type: integer format: int64 example: 1 date: type: string format: date-time example: '2019-11-06T00:00:00Z' cumulativePayloadTotal: type: object nullable: true properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' payload: type: integer format: int64 example: 1 cumulativeActiveRegenerationHours: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string hours: example: 15 format: int64 nullable: true type: integer cumulativePowerTakeOffHours: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string hours: example: 12 format: int64 nullable: true type: integer peakDailySpeed: type: object nullable: true properties: date: example: '2019-11-06T00:00:00Z' format: date-time nullable: true type: string speed: example: 100.5 format: float nullable: true type: number averageDailyEngineLoadFactor: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 88.24 DEFRemainingRatio: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 58.24 cumulativeIdleHours: type: object nullable: true properties: date: type: string format: date-time hours: example: 12 format: int64 nullable: true type: integer fuelRemaining: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true percent: type: number format: float example: 65.5 engineCondition: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true running: type: boolean description: True if the engine was running at `date`, false if it was off. Null when the equipment has no engine state. nullable: true example: true nextMaintenance: type: object properties: date: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: false nextMaintenanceDate: type: string format: date-time example: '2019-11-06T00:00:00Z' nullable: true usageHoursUntilNextMaintenance: type: number format: float example: 505 nullable: true kmUntilNextMaintenance: type: number format: float example: 1250 nullable: true evBatteryLevel: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 76.5 evBatteryTemperature: type: object nullable: true properties: date: type: string format: date-time celsius: type: number format: float example: 35.2 evBatteryHealth: type: object nullable: true properties: date: type: string format: date-time percent: type: number format: float example: 92.3 evBatteryVoltage: type: object nullable: true properties: date: type: string format: date-time volts: type: number format: float example: 400.5 evBatteryChargingState: type: object nullable: true properties: date: type: string format: date-time state: type: string example: charging chargingMode: type: string example: ac evBatteryCurrent: type: object nullable: true properties: date: type: string format: date-time amperes: type: number format: float example: 150 evChargingRate: type: object nullable: true properties: date: type: string format: date-time watts: type: number format: float example: 7400 evDischargingRate: type: object nullable: true properties: date: type: string format: date-time watts: type: number format: float example: 3200 evBatteryChargeCyclesCount: type: object nullable: true properties: date: type: string format: date-time count: type: integer format: int64 example: 250 evEnergyUsed: type: object nullable: true properties: date: type: string format: date-time wattHours: type: number format: float example: 45000 evEnergyCharged: type: object nullable: true properties: date: type: string format: date-time wattHours: type: number format: float example: 50000 activities: description: Time series of activities for a specific asset content: application/json: schema: type: object properties: data: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: dateStart: type: string format: date-time description: Start date and time of the activity example: '2019-11-06T08:00:00Z' dateStop: type: string format: date-time description: End date and time of the activity example: '2019-11-06T09:30:00Z' distanceMeters: type: number format: float description: Distance traveled during the activity in meters example: 15420.5 averageSpeedKmH: type: number format: float description: Average speed during the activity in kilometers per hour example: 12.8 firstPositionAddress: type: string description: Address of the first recorded position example: 123 Main St, Springfield, IL lastPositionAddress: type: string description: Address of the last recorded position example: 456 Oak Ave, Springfield, IL id: type: integer example: 1 serialNumber: type: string example: YVR001988 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' faults: description: Time series of fault codes for a specific asset content: application/json: schema: type: object properties: data: type: object properties: total: type: number format: int64 example: 2 rows: type: array items: type: object properties: date: type: string format: date-time description: Date and time when the fault was recorded description: type: string description: Human-readable description of the fault identifier: type: string description: Fault code identifier/label severity: type: integer description: Numerical severity level of the fault levelLabel: type: string description: Human-readable severity level label example: - date: '2019-11-06T14:30:00Z' description: Engine coolant temperature too high identifier: P0217 severity: 3 levelLabel: High - date: '2019-11-06T15:45:00Z' description: Low fuel pressure identifier: P0087 severity: 2 levelLabel: Medium id: type: integer example: 1 serialNumber: type: string example: YVR001988 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' positions: description: Time series of positions for a specific asset content: application/json: schema: type: object properties: data: type: object properties: total: type: number format: int64 example: 2 rows: type: array items: type: object properties: date: type: string format: date-time description: Date and time when the position was recorded latitude: type: number format: float description: Latitude coordinate in decimal degrees longitude: type: number format: float description: Longitude coordinate in decimal degrees altitude: type: number format: float nullable: true description: Altitude in meters above sea level speed: type: number format: float nullable: true description: Speed in kilometers per hour heading: type: number format: float nullable: true description: Heading/direction in degrees (0-360) postalAddress: type: string nullable: true description: Reverse geocoded address of the position. Null when no address could be resolved for these coordinates. example: - date: '2019-11-06T14:30:00Z' latitude: 48.844457 longitude: 2.383023 altitude: 35 speed: 25.5 heading: 125.3 postalAddress: 5 Avenue Anatole France, 75007 Paris, France - date: '2019-11-06T14:35:00Z' latitude: 48.846123 longitude: 2.385678 altitude: 38 speed: 32.1 heading: 130.7 postalAddress: null id: type: integer example: 1 serialNumber: type: string example: YVR001988 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' tyreSnapshot: description: Time series of tyre readings for a specific asset content: application/json: schema: type: object properties: data: type: object properties: total: type: number format: int64 example: 2 rows: type: array description: One row per tyre and per reading, most recent reading first. items: type: object properties: date: type: string format: date-time description: Date and time when the tyre reading was recorded isoPositionIndex: type: integer description: | Position of the tyre on the equipment, encoded as `axle × 16 + wheel position`. Axles are numbered from 1, starting at the front. Wheel positions, from left to right, are 6 and 7 on the left side and 9 and 10 on the right side; 7 and 9 are the tyres closest to the centre of the axle. For example, 22 is the left outer tyre of axle 1 and 41 is the right inner tyre of axle 2. In hexadecimal, the first digit is the axle and the second the wheel position (22 = 0x16). temperature: type: number format: float nullable: true description: Tyre temperature in degrees Celsius. Null when the sensor does not report it. pressure: type: number format: float nullable: true description: Tyre pressure in pascals (Pa). Divide by 100,000 to get bar. signalQuality: type: string nullable: true description: Quality of the radio signal between the tyre sensor and the receiver (`good`, `warning` or `poor`). Only some data sources report it; null otherwise. signalQualityScore: type: integer nullable: true description: Signal quality score as reported by the data source. Null when the data source does not report it. flags: type: array nullable: true items: type: string description: Alerts raised by the tyre monitoring system for this tyre, such as `low pressure` or `high tyre temperature`. The values depend on the data source. Empty when no alert is raised. example: - date: '2019-11-06T14:30:00Z' isoPositionIndex: 38 temperature: 31.5 pressure: 820000 signalQuality: good signalQualityScore: 31 flags: [] - date: '2019-11-06T14:30:00Z' isoPositionIndex: 39 temperature: 33 pressure: 655000 signalQuality: good signalQualityScore: 28 flags: - low pressure id: type: integer example: 1 serialNumber: type: string example: YVR001988 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' SnapshotOfEquipmentDataKind: description: | Snapshot of all devices. The shape of each row varies by data kind — this example shows `fuelRemaining`. For `dailyFuel` and `dailyCO2`, rows also include an `estimated` boolean: whether the value was estimated from usage hours × the model's consumption rate, rather than measured from telematics. content: application/json: schema: type: object properties: data: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: percent: type: number format: float description: | Percentage of fuel remaining in the asset's tank. example: 88.24 date: type: string format: date-time id: type: integer example: 1 serialNumber: type: string example: YVR001988 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' EquipmentHistory: description: Specific equipment details with its history content: application/json: schema: type: object properties: data: type: object properties: id: type: integer example: 1 name: type: string example: D8000-1 make: type: string example: Caterpillar model: type: string example: '8000' serialNumber: type: string example: YVR001988 pin: type: string nullable: true description: Product Identification Number example: '12345678901234567' vin: type: string nullable: true description: Vehicle Identification Number example: 1HGBH41JXMN109186 positions: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: latitude: type: number format: float example: 48.858269 longitude: type: number format: float example: 2.29447 date: type: string format: date-time altitude: type: number format: float nullable: true description: Altitude in meters above sea level example: 35 speed: type: number format: float nullable: true description: Speed in kilometers per hour example: 25.5 heading: type: number format: float nullable: true description: Heading/direction in degrees (0-360) example: 125.3 postalAddress: type: string nullable: true description: Reverse geocoded address of the position. Null when no address could be resolved for these coordinates. example: 5 Avenue Anatole France, 75007 Paris, France faultCodes: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: levelLabel: type: string nullable: true enum: - unknown - information - warning - error - critical severity: type: number format: int64 nullable: true enum: - -1 - 0 - 1 - 2 description: | Severity of the error * -1 - Unknown * 0 - Information * 1 - Warning * 2 - Error identifier: type: string description: type: string date: type: string format: date-time fuelRemainings: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: percent: type: number format: float description: | Perentage of fuel remaining in the asset's tank. example: 88.24 date: type: string format: date-time engineConditions: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: running: type: boolean description: | Engine state at `date`: true if the engine was on or idling, false if it was off. date: type: string format: date-time dailyUsages: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: date: type: string format: date-time operatingHours: type: object description: The total number of engine hours on this date properties: hour: nullable: true type: number format: float example: 8.3 idleHours: type: object description: The total number of idle engine hours on this date properties: hour: nullable: true type: number format: float example: 1.5 workingHours: type: object description: The total number of "useful" e.g. non-idle engine hours on this date properties: hour: nullable: true type: number format: float example: 6.8 fuelUsed: type: object description: The total of liter of fuel used on this date properties: fuelUsed: nullable: true type: number format: float example: 99.7 unit: type: string example: L estimated: nullable: true type: boolean description: | Whether this value was estimated from usage hours × the model's consumption rate, rather than measured from telematics. example: false dailyDistance: type: object description: Number of kilometers traveled on this date properties: odometer: nullable: true type: number format: float example: 54.2 unit: type: string example: km cumulativeIdleHours: description: The last available cumulativeIdleHours of the day or null if none available type: object properties: hour: type: number format: float example: 1064.6 nullable: true cumulativeOperatingHours: description: The last available cumulativeOperatingHours of the day or null if none available type: object properties: hour: type: number format: float example: 1064.6 nullable: true cumulativeFuelUsed: description: The last available cumulativeFuelUsed of the day or null if none available type: object properties: fuelUsed: type: number format: float example: 9520.5 unit: type: string example: L cumulativeDistance: description: The last available cumulativeDistance of the day or null if none available type: object properties: odometer: type: number format: float example: 5423.9 unit: type: string example: km cumulativeLoadCount: description: The number of cycles performed by the machine. type: object properties: count: nullable: true type: integer format: int64 example: 13569 cumulativePayloadTotal: description: Total payload lifted, hauled or processed by the machine. type: object properties: payload: type: number format: float example: 447839.9 payloadUnit: type: string example: tonnes cumulativeActiveRegenerationHours: description: The time when the machine is placed in a non-productive state to complete the regeneration process. type: object properties: hour: nullable: true type: number format: float example: 10.92 cumulativePowerTakeOffHours: type: object description: The time the power take off was driving an implement such as a mower or sprayer. properties: hour: nullable: true type: number format: float example: 31.21 peakDailySpeed: description: Used to monitor excessive machine speed to identify machine misuse or underuse. type: object properties: speed: type: number format: float example: 14.91 speedUnit: type: string example: km/h averageDailyEngineLoadFactor: description: The percentage calculated as the actual fuel consumed over the previous 24 h period divided by the fuel that would have been consumed during that period if the machine had been continually operated at the engine’s rated output. type: object properties: percent: type: number format: float example: 35.9 DEFRemainingRatio: type: object properties: percent: type: number format: float description: The percent of DEF — Diesel exhaust fluid — remaining is used to schedule DEF delivery to the vehicle example: 62 tankCapacity: type: number format: float description: The maximum capacity of the DEF tank. example: 41 tankCapacityUnit: type: string example: L co2: description: Total CO2 emitted by the machine. type: object properties: weight: type: number format: float example: 123 unit: type: string example: kg estimated: nullable: true type: boolean description: | Whether this value was estimated from usage hours × the model's consumption rate, rather than measured from telematics. example: false EquipmentsHistory: description: List of equipment with their history content: application/json: schema: type: object properties: data: type: object properties: total: type: integer format: int32 example: 1 since: type: string format: date-time description: The since value actually used example: '2019-11-06T00:00:00Z' until: type: string format: date-time description: The until value actually used example: '2019-11-20T23:59:59Z' rows: type: array items: type: object properties: id: type: integer example: 1 name: type: string example: D8000-1 make: type: string example: Caterpillar model: type: string example: '8000' serialNumber: type: string example: YVR001988 positions: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: latitude: type: number format: float example: 48.858269 longitude: type: number format: float example: 2.29447 date: type: string format: date-time altitude: type: number format: float nullable: true description: Altitude in meters above sea level example: 35 speed: type: number format: float nullable: true description: Speed in kilometers per hour example: 25.5 heading: type: number format: float nullable: true description: Heading/direction in degrees (0-360) example: 125.3 postalAddress: type: string nullable: true description: Reverse geocoded address of the position. Null when no address could be resolved for these coordinates. example: 5 Avenue Anatole France, 75007 Paris, France faultCodes: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: severity: type: number format: int64 nullable: true enum: - -1 - 0 - 1 - 2 description: | Severity of the error * -1 - Unknown * 0 - Information * 1 - Warning * 2 - Error identifier: type: string description: type: string date: type: string format: date-time fuelRemainings: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: percent: type: number format: float description: | Perentage of fuel remaining in the asset's tank. example: 88.24 date: type: string format: date-time engineConditions: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: running: type: boolean description: | Engine state at `date`: true if the engine was on or idling, false if it was off. date: type: string format: date-time dailyUsages: type: object properties: total: type: number format: int64 example: 1 rows: type: array items: type: object properties: date: type: string format: date-time operatingHours: type: object description: The total number of engine hours on this date properties: hour: nullable: true type: number format: float example: 8.3 idleHours: type: object description: The total number of idle engine hours on this date properties: hour: nullable: true type: number format: float example: 1.5 workingHours: type: object description: The total number of "useful" e.g. non-idle engine hours on this date properties: hour: nullable: true type: number format: float example: 6.8 fuelUsed: type: object description: The total of liter of fuel used on this date properties: fuelUsed: nullable: true type: number format: float example: 99.7 unit: type: string example: L dailyDistance: type: object description: Number of kilometers traveled on this date properties: odometer: nullable: true type: number format: float example: 54.2 unit: type: string example: km cumulativeIdleHours: description: The last available cumulativeIdleHours of the day or null if none available type: object properties: hour: type: number format: float example: 1064.6 nullable: true cumulativeOperatingHours: description: The last available cumulativeOperatingHours of the day or null if none available type: object properties: hour: type: number format: float example: 1064.6 nullable: true cumulativeFuelUsed: description: The last available cumulativeFuelUsed of the day or null if none available type: object properties: fuelUsed: type: number format: float example: 9520.5 unit: type: string example: L cumulativeDistance: description: The last available cumulativeDistance of the day or null if none available type: object properties: odometer: type: number format: float example: 5423.9 unit: type: string example: km cumulativeLoadCount: description: The number of cycles performed by the machine. type: object properties: count: nullable: true type: integer format: int64 example: 13569 cumulativePayloadTotal: description: Total payload lifted, hauled or processed by the machine. type: object properties: payload: type: number format: float example: 447839.9 payloadUnit: type: string example: tonnes cumulativeActiveRegenerationHours: description: The time when the machine is placed in a non-productive state to complete the regeneration process. type: object properties: hour: nullable: true type: number format: float example: 10.92 cumulativePowerTakeOffHours: type: object description: The time the power take off was driving an implement such as a mower or sprayer. properties: hour: nullable: true type: number format: float example: 31.21 peakDailySpeed: description: Used to monitor excessive machine speed to identify machine misuse or underuse. type: object properties: speed: type: number format: float example: 14.91 speedUnit: type: string example: km/h averageDailyEngineLoadFactor: description: The percentage calculated as the actual fuel consumed over the previous 24 h period divided by the fuel that would have been consumed during that period if the machine had been continually operated at the engine’s rated output. type: object properties: percent: type: number format: float example: 35.9 DEFRemainingRatio: type: object properties: percent: type: number format: float description: The percent of DEF — Diesel exhaust fluid — remaining is used to schedule DEF delivery to the vehicle example: 62 tankCapacity: type: number format: float description: The maximum capacity of the DEF tank. example: 41 tankCapacityUnit: type: string example: L Equipments: description: List of equipment content: application/json: schema: type: object properties: data: type: object properties: total: type: integer format: int64 example: 1 rows: type: array items: type: object properties: id: type: integer example: 1 name: type: string example: D8000-1 make: type: string example: Caterpillar model: type: string example: '8000' serialNumber: type: string example: YVR001988 pin: type: string nullable: true description: Product Identification Number example: '12345678901234567' vin: type: string nullable: true description: Vehicle Identification Number example: 1HGBH41JXMN109186 workspaces: type: array items: type: string example: Workspace 1 customFields: type: array items: type: object properties: name: type: string example: Custom Field 1 value: type: string example: Value 1 group: type: object properties: id: type: integer example: 10 assetIds: type: array items: type: integer example: - 1 - 2 - 3 Archived: description: List of archived equipment content: application/json: schema: type: object properties: data: type: object properties: total: type: integer format: int64 example: 1 rows: type: array items: type: object properties: id: type: integer example: 1 archiveComment: type: string description: A comment about why the equipment was archived example: No longer in use archiveDate: type: string description: The date at which the equipment was last archived serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ) format: date-time example: '2025-01-01T00:00:00Z' Equipment: description: List of equipment content: application/json: schema: type: object properties: data: type: object properties: id: type: integer example: 1 name: type: string example: D8000-1 make: type: string example: Caterpillar model: type: string example: '8000' serialNumber: type: string example: YVR001988 pin: type: string nullable: true description: Product Identification Number example: '12345678901234567' vin: type: string nullable: true description: Vehicle Identification Number example: 1HGBH41JXMN109186 workspaces: type: array items: type: string example: Workspace 1 customFields: type: array items: type: object properties: name: type: string example: Custom Field 1 value: type: string example: Value 1 400Error: description: Missing or invalid parameters. `details` lists each invalid field with a stable `code`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: message: Invalid parameters code: INVALID_PARAMETERS details: - field: recipient code: INVALID_FORMAT message: Invalid email address - field: assetIds code: TOO_SMALL message: 'Too small: expected array to have >=1 items' 403Error: description: Insufficient permissions to access the resource content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Not authorized to access route 404Error: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Not Found 400LegacyError: description: Missing parameters or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid input details: {} Workspaces: description: List of equipment content: application/json: schema: type: object properties: data: type: object properties: total: type: integer format: int64 example: 1 rows: type: array items: type: object properties: name: type: string example: All fleet 500Error: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Internal server error 204Success: description: No Content 409Error: description: Conflict content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Conflict 422Error: description: Invalid input or missing parameters content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Invalid input data paths: /login: post: operationId: login summary: Authenticate on the API description: Authenticate on the API with your credentials to get a token that you can use in your requests. The token is valid for 10 days. security: [] tags: - Login requestBody: required: true content: application/json: schema: type: object required: - name - apiKey properties: name: type: string example: api_company apiKey: type: string example: 2ddd4027-c779-4b7c-80fe-8661c92c35ff responses: '200': description: Token to use in the other API calls content: application/json: schema: type: object properties: id: type: integer example: 42 email: type: string example: api@hiboo.io admin: type: boolean example: false firstName: type: string example: John lastName: type: string example: Doe token: type: string example: eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ '401': description: The name or the API key is wrong, or the API credential is deactivated. content: application/json: schema: $ref: '#/components/schemas/NoDetailError' example: message: Validation failed. Given credentials aren't matching. /v2/fleet/equipments/snapshot: get: operationId: getFleetEquipmentsSnapshot summary: Fleet description: Returns the last information available for all data kinds for the fleet. This endpoint is paginated. tags: - Snapshot parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - name: search in: query description: Optional - if provided it will return the equipment with a fleet number or serialNumber matching the parameter required: false schema: type: string - $ref: '#/components/parameters/FilterByInProgressSharing' responses: '200': $ref: '#/components/responses/SnapshotOfAllEquipments' '401': $ref: '#/components/responses/401Error' /v2/iso15143-3/Fleet/{pageNumber}: get: operationId: getFleetAEMP summary: Fleet following ISO 15143-3 (AEMP) description: Returns the list of all equipments and their latest data. This endpoint is paginated. tags: - Snapshot parameters: - name: pageNumber in: path description: Page number to retrieve. The page number starts at 1. required: true schema: type: integer format: int32 default: 1 - $ref: '#/components/parameters/FilterByInProgressSharing' responses: '200': $ref: '#/components/responses/EquipmentsISO15143' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/snapshot: get: operationId: getFleetEquipmentSnapshotByEquipmentId summary: Equipment description: Returns the last information available for all data kinds for specific equipment tags: - Snapshot parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 responses: '200': $ref: '#/components/responses/SnapshotOfSpecificEquipment' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/activities: get: operationId: getFleetEquipmentActivities summary: Activity history description: Returns all activities (trips/movements) for a specific piece of equipment. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - $ref: '#/components/parameters/since' - $ref: '#/components/parameters/until' responses: '200': $ref: '#/components/responses/activities' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/faults: get: operationId: getFleetEquipmentFaults summary: Fault history description: Returns all fault codes for a specific piece of equipment. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - $ref: '#/components/parameters/since' - $ref: '#/components/parameters/until' responses: '200': $ref: '#/components/responses/faults' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/positions: get: operationId: getFleetEquipmentPositions summary: Position history description: Returns all GPS positions for a specific piece of equipment. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - $ref: '#/components/parameters/since' - $ref: '#/components/parameters/until' responses: '200': $ref: '#/components/responses/positions' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/tyreSnapshot: get: operationId: getFleetEquipmentTyreSnapshot summary: Tyre history description: Returns the tyre pressure and temperature readings (TPMS) for a specific piece of equipment. Each row is the reading of one tyre at one point in time, so a reading of a six-tyre vehicle gives six rows. Rows are sorted from the most recent reading. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - $ref: '#/components/parameters/since' - $ref: '#/components/parameters/until' responses: '200': $ref: '#/components/responses/tyreSnapshot' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/{dataKind}: get: operationId: getFleetEquipmentDataKindByEquipmentId summary: Data kind history description: Returns time series data for a specific data kind for a piece of equipment. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - name: dataKind in: path description: Data kind identifier. required: true schema: type: string enum: - activities - averageDailyEngineLoadFactor - batteryLevel - batteryVoltage - cumulativeActiveRegenerationHours - cumulativeDistance - cumulativeFuel - cumulativeIdleFuel - cumulativeIdleHours - cumulativeLoadCount - cumulativeOperatingHours - cumulativePayloadTotal - cumulativePowerTakeOffHours - dailyCO2 - dailyDistance - dailyEvEnergyUsed - dailyIdleFuel - dailyLoadCount - dailyPayload - dailyUsages - defRemainingRatio - deviceBatteryLevel - deviceBatteryVoltage - engineCondition - engineCoolantTemperature - engineLoadPercentage - evBatteryChargeCyclesCount - evBatteryCurrent - evBatteryHealth - evBatteryLevel - evBatteryTemperature - evBatteryVoltage - evChargingRate - evChargingState - evDischargingRate - evEnergyCharged - evEnergyUsed - faults - fuelRemaining - peakDailySpeed - positions - sensorBoolean - temperature - tyreSnapshot example: batteryLevel - name: since in: query required: false description: Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is beginning of yesterday UTC - name: until in: query required: false description: Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is end of today UTC responses: '200': $ref: '#/components/responses/SnapshotOfEquipmentDataKind' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}/history: get: operationId: getFleetEquipmentHistoryByEquipmentId summary: Daily history description: Returns comprehensive daily history for a piece of equipment including positions, usage, and fault codes. tags: - Time Series parameters: - $ref: '#/components/parameters/assetId' - name: since in: query required: false description: Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is beginning of yesterday UTC - name: until in: query required: false description: Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is end of today UTC responses: '200': $ref: '#/components/responses/EquipmentHistory' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/history: get: deprecated: true operationId: getFleetEquipmentsHistory summary: Fleet description: ⚠️ This endpoint will be deprecated and should not be used anymore. Returns the list of all equipments and their history (positions, daily usages, fault codes). This endpoint is paginated. tags: - Time Series parameters: - name: since in: query required: false description: Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is beginning of yesterday UTC - name: until in: query required: false description: Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ' schema: type: string format: date-time description: Default is end of today UTC - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' responses: '200': $ref: '#/components/responses/EquipmentsHistory' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments: get: operationId: getFleetEquipments summary: Fleet description: Returns the list of all equipments and their identity. This endpoint is paginated. tags: - Fleet parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/includeCustomFields' - $ref: '#/components/parameters/includeDataSources' - $ref: '#/components/parameters/includeGroup' - $ref: '#/components/parameters/FilterByInProgressSharing' responses: '200': $ref: '#/components/responses/Equipments' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/archived: get: operationId: getArchivedFleetEquipments summary: Archived Equipments description: Returns the list of archived equipments. This endpoint is paginated. tags: - Fleet parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' responses: '200': $ref: '#/components/responses/Archived' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipments/{id}: get: operationId: getFleetEquipment summary: Equipment description: Returns the identity of the requested equipment tags: - Fleet parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 - $ref: '#/components/parameters/includeCustomFields' responses: '200': $ref: '#/components/responses/Equipment' '401': $ref: '#/components/responses/401Error' delete: operationId: deleteFleetEquipment summary: Delete an equipment description: Marks the specified equipment as deleted. The equipment must be archived before it can be mark as deleted. tags: - Fleet parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 responses: '204': description: Equipment deleted successfully (no content) '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Equipment cannot be deleted unless it is archived first, or if it is currently involved in an in progress sharing process. /v2/fleet/equipments/{id}/status: get: operationId: getFleetEquipmentStatus summary: Get equipment status description: Returns the current status of the specified equipment. The response includes metadata depending on the status tags: - Fleet parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 responses: '200': description: Equipment status retrieved successfully content: application/json: schema: type: object properties: status: type: string enum: - archived - deleted - active description: Current status of the equipment metadata: type: object nullable: true description: Additional metadata depending on the status properties: date: type: string format: date-time description: Timestamp when the status change occurred comment: type: string description: Comment associated with archiving (only present if status is archived) required: - status examples: archived: summary: Archived equipment value: status: archived metadata: date: '2024-12-01T10:30:00Z' comment: End-of-life; replaced by new model deleted: summary: Deleted equipment value: status: deleted metadata: date: '2025-01-15T14:00:00Z' active: summary: Active equipment value: status: active '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' /v2/fleet/equipments/{id}/status/archived: post: operationId: archiveFleetEquipment summary: Archive an equipment description: Marks the specified equipment as archived. Archived equipment will no longer be active, but can be restored later using the `/status/active` endpoint. tags: - Fleet parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 requestBody: required: true content: application/json: schema: type: object required: - comment properties: comment: type: string description: Reason or note for archiving the equipment example: Equipment is no longer in use and has been replaced responses: '204': description: Equipment archived successfully (no content) '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Equipment must be active before it can be archived /v2/fleet/equipments/{id}/status/active: post: operationId: unarchiveFleetEquipment summary: Unarchive an equipment description: Restores a previously archived equipment to active status. tags: - Fleet parameters: - name: id in: path description: ID of the equipment required: true schema: type: integer format: int32 responses: '204': description: Equipment unarchived successfully (no content) '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Equipment must be archived before it can be unarchived /v2/fleet/equipment: patch: operationId: updateFleetEquipment summary: Update Equipment Identity description: Update equipment data with assetId or (serialNumber AND make) tags: - Equipment Identity requestBody: content: application/json: schema: $ref: '#/components/schemas/asset' responses: '200': description: Equipment has been modified content: application/json: schema: properties: status: type: string example: OK '400': $ref: '#/components/responses/400LegacyError' '401': $ref: '#/components/responses/401Error' '500': description: An error occurred while processing the request content: application/json: schema: properties: status: type: string example: KO /v2/fleet/workspaces: get: operationId: getFleetWorkspaces summary: Workspaces description: Returns the list of all workspaces available tags: - Workspaces responses: '200': $ref: '#/components/responses/Workspaces' '401': $ref: '#/components/responses/401Error' /v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces: post: operationId: linkAssetToWorkspaces summary: Add Equipment to Workspaces description: Add asset workspaces data with assetId or (serialNumber AND make) of Asset and workspace names tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/bodyAssetWorkspaceNames' responses: '200': description: Equipment has been added content: application/json: schema: properties: status: type: string example: OK '400': $ref: '#/components/responses/400LegacyError' '401': $ref: '#/components/responses/401Error' '500': description: An error occurred while processing the request content: application/json: schema: properties: status: type: string example: KO delete: operationId: deleteLinkAssetToWorkspaces summary: Remove Equipment from Workspaces description: delete link asset and workspaces data with assetId or (serialNumber AND make) of Asset and workspace names tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/bodyAssetWorkspaceNames' responses: '200': description: Equipment has been unlink between asset and workspace content: application/json: schema: properties: status: type: string example: OK '400': $ref: '#/components/responses/400LegacyError' '401': $ref: '#/components/responses/401Error' '500': description: An error occurred while processing the request content: application/json: schema: properties: status: type: string example: KO /v2/fleet/equipment/assetCustomFields: post: operationId: addFleetEquipmentAssetCustomFields summary: Add Custom Fields to Equipment description: add assetCustomFields data with assetId or (serialNumber AND make) tags: - Equipment Identity requestBody: content: application/json: schema: $ref: '#/components/schemas/bodyAssetCustomFields' responses: '200': description: AssetCustomFields has been added content: application/json: schema: properties: status: type: string example: OK '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '500': description: An error occurred while processing the request content: application/json: schema: properties: status: type: string example: KO delete: operationId: deleteFleetEquipmentAssetCustomFields summary: Remove Custom Fields from Equipment description: delete assetCustomFields data with assetId or (serialNumber AND make) tags: - Equipment Identity requestBody: content: application/json: schema: $ref: '#/components/schemas/bodyAssetCustomFields' responses: '200': description: AssetCustomFields has been deleted content: application/json: schema: properties: status: type: string example: OK '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '500': description: An error occurred while processing the request content: application/json: schema: properties: status: type: string example: KO /v2/fleet/equipments/{id}/documents: get: summary: Get documents for a specific equipment description: Retrieve a list of documents for the specified equipment. tags: - Equipment Documents operationId: listDocuments parameters: - name: id description: The unique identifier of the equipment. in: path required: true schema: type: integer - $ref: '#/components/parameters/offset' - name: limit in: query required: false schema: default: 10 type: integer description: The number of items to return responses: '200': description: A paginated list of documents for the equipment content: application/json: schema: type: object properties: total: type: integer description: The total number of documents for the equipment offset: type: integer description: The number of items skipped limit: type: integer description: The number of items returned rows: type: array description: The list of documents items: $ref: '#/components/schemas/Document' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '404': $ref: '#/components/responses/404Error' post: summary: Upload a document for a specific equipment description: Upload a document to be associated with the specified equipment. tags: - Equipment Documents operationId: uploadDocument parameters: - name: id description: The unique identifier of the equipment. in: path required: true schema: type: integer requestBody: description: More information about the required payload required: true content: multipart/form-data: schema: $ref: '#/components/schemas/UploadDocumentBody' encoding: file: contentType: application/pdf, image/jpeg, image/png, image/gif, image/tiff, text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document responses: '201': description: Document successfully uploaded content: application/json: schema: $ref: '#/components/schemas/Document' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Conflict with existing document metadata (e.g., duplicate name) '413': description: Payload Too Large. File should not exceeds 10MB '415': description: Unsupported Media Type /v2/fleet/equipments/{id}/documents/{documentId}: patch: summary: Update document metadata description: Update the metadata (e.g., name, isPublic) of a specific document associated with the specified equipment. tags: - Equipment Documents operationId: updateDocument parameters: - name: id description: The unique identifier of the equipment. in: path required: true schema: type: integer - name: documentId in: path description: The unique identifier of the document. required: true schema: type: integer requestBody: description: Update an existing document content: application/json: schema: $ref: '#/components/schemas/PatchDocumentBody' required: true responses: '200': description: Document metadata successfully updated content: application/json: schema: $ref: '#/components/schemas/Document' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Conflict with existing document metadata (e.g., duplicate name) delete: summary: Delete a specific document description: Deletes a specific document associated with the specified equipment. tags: - Equipment Documents operationId: deleteDocument parameters: - name: id description: The unique identifier of the equipment. in: path required: true schema: type: integer - name: documentId description: The unique identifier of the document. in: path required: true schema: type: integer responses: '204': description: Document successfully deleted '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' /v2/fleet/equipments/{id}/documents/{documentId}/download: get: summary: Download a specific document description: Allows the user to download a specific document associated with the specified equipment. tags: - Equipment Documents operationId: downloadDocument parameters: - name: id description: The unique identifier of the equipment. in: path required: true schema: type: integer - name: documentId description: The unique identifier of the document. in: path required: true schema: type: integer responses: '200': description: Document successfully downloaded content: application/octet-stream: schema: type: string format: binary '401': $ref: '#/components/responses/401Error' '404': $ref: '#/components/responses/404Error' /v2/fleet/groups: post: summary: Create a new equipment group description: Create a new group by linking multiple equipments together. At least 2 equipment IDs are required. tags: - Equipment Groups operationId: createGroup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGroupBody' responses: '201': $ref: '#/components/responses/201' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403' '409': $ref: '#/components/responses/409' /v2/fleet/groups/{id}: put: summary: Update an equipment group description: Update an existing equipment group by replacing the list of equipments. At least 2 equipment IDs are required. tags: - Equipment Groups operationId: updateGroup parameters: - name: id description: The unique identifier of the group to update. in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGroupBody' responses: '200': description: Group successfully updated content: application/json: schema: $ref: '#/components/schemas/GroupBodySerialized' '400': description: Invalid parameters. A group needs at least 2 equipments; when `assetIds` contains fewer than 2 IDs, `details` contains an entry with `field` `assetIds` and `code` `TOO_SMALL`. When `id` is not a number, `details` contains an entry with `field` `id` and `code` `INVALID_TYPE`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: message: Invalid parameters code: INVALID_PARAMETERS details: - field: assetIds code: TOO_SMALL message: 'Too small: expected array to have >=2 items' '401': $ref: '#/components/responses/401Error' '403': description: Insufficient permissions to edit this group content: application/json: schema: $ref: '#/components/schemas/NoDetailError' '404': description: Group not found content: application/json: schema: $ref: '#/components/schemas/NoDetailError' '409': description: One or more equipments are already part of another group content: application/json: schema: $ref: '#/components/schemas/Error' delete: summary: Delete an equipment group description: Delete an existing equipment group. This will unlink all equipments from the group. tags: - Equipment Groups operationId: deleteGroup parameters: - name: id description: The unique identifier of the group to delete. in: path required: true schema: type: integer responses: '204': description: Group successfully deleted '400': description: Invalid parameters. When `id` is not a number, `details` contains an entry with `field` `id` and `code` `INVALID_TYPE`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: message: Invalid parameters code: INVALID_PARAMETERS details: - field: id code: INVALID_TYPE message: 'Invalid input: expected number, received NaN' '401': $ref: '#/components/responses/401Error' '403': description: Insufficient permissions to delete this group content: application/json: schema: $ref: '#/components/schemas/NoDetailError' /v2/fleet/sharings: post: tags: - Hiboo Connect summary: Create a new Sharing description: This endpoint will allow you to create a new instance of Sharing. It can be a contract for instance. operationId: addSharing requestBody: description: More information about the required payload content: application/json: schema: $ref: '#/components/schemas/CreateSharingBody' required: true responses: '201': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Sharing' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '409': description: Unique reference is already used by another sharing content: application/json: schema: $ref: '#/components/schemas/NoDetailError' get: tags: - Hiboo Connect summary: List Sharing description: Returns all Sharing instances that have been created operationId: listSharing parameters: - name: offset in: query required: true example: 10 schema: type: integer description: The number of items to skip before starting to collect the result set - name: limit in: query required: true example: 10 schema: type: integer description: The number of items to return - name: status in: query required: false example: in_progress schema: type: string enum: - pending - planned - in_progress - stopped - completed description: Filter by sharing status - name: assetId in: query required: false example: 1 schema: type: integer description: Filter by asset ID responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Sharing' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' /v2/fleet/sharings/{reference}: get: tags: - Hiboo Connect summary: Get a sharing description: Returns a single sharing by reference operationId: getSharing parameters: - name: reference in: path description: The reference you defined when creating the sharing required: true schema: type: string example: contract-4242-2024 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Sharing' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' patch: tags: - Hiboo Connect summary: Update an existing sharing description: Update an existing sharing by reference operationId: updateSharing parameters: - name: reference in: path description: The reference you defined when creating the Sharing required: true schema: type: string example: contract-4242-2024 requestBody: description: Partial update of an existing sharing resource. Only the provided fields will be updated. content: application/json: schema: $ref: '#/components/schemas/PatchSharingBody' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Sharing' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Sharing has already started content: application/json: schema: $ref: '#/components/schemas/NoDetailError' delete: tags: - Hiboo Connect summary: Delete a Sharing description: It totally deletes a Sharing as it never existed. This will only work if the Sharing has not started yet. operationId: deleteSharing parameters: - name: reference in: path description: The reference you defined when creating the Sharing required: true schema: type: string example: contract-4242-2024 responses: '204': description: Sharing was successfully deleted '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: Sharing cannot be deleted because it has already started or ended content: application/json: schema: $ref: '#/components/schemas/Error' /v2/fleet/sharings/{reference}/in-progress: delete: tags: - Hiboo Connect summary: Stop the sharing description: This endpoint will stop the sharing of data for the specified reference. It will not delete the sharing, but it will stop the data sharing process. operationId: stopSharing parameters: - name: reference in: path description: The reference you defined when creating the Sharing required: true schema: type: string example: contract-4242-2024 responses: '204': description: successful operation '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': description: if the Sharing is not in progress content: application/json: schema: $ref: '#/components/schemas/Error' /v2/fleet/contracts/assignments: post: tags: - Contracts summary: Create a contract assignment description: Assigns an equipment to a contract for a given period. The contract assignment defines the expected usage of the equipment (working days, maximum hours per day), which is used to detect out-of-contract usage. operationId: createContractAssignment requestBody: description: The contract assignment to create content: application/json: schema: $ref: '#/components/schemas/CreateContractAssignmentBody' required: true responses: '201': description: Contract assignment successfully created content: application/json: schema: $ref: '#/components/schemas/ContractAssignment' '400': description: Missing parameters or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': description: Equipment not found in your organization content: application/json: schema: $ref: '#/components/schemas/NoDetailError' get: tags: - Contracts summary: List contract assignments description: Returns all the contract assignments of your organization operationId: listContractAssignments responses: '200': description: Successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/ContractAssignment' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' /v2/fleet/contracts/assignments/{id}: put: tags: - Contracts summary: Update a contract assignment description: Replaces an existing contract assignment with the provided representation. All the fields must be provided; the contract reference and the equipment cannot be changed. operationId: editContractAssignment parameters: - name: id in: path description: The id of the contract assignment, returned when it was created required: true schema: type: integer format: int32 example: 42 requestBody: description: The new values of the contract assignment content: application/json: schema: $ref: '#/components/schemas/EditContractAssignmentBody' required: true responses: '200': description: Contract assignment successfully updated content: application/json: schema: $ref: '#/components/schemas/ContractAssignment' '400': description: Missing parameters or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': description: Contract assignment not found content: application/json: schema: $ref: '#/components/schemas/NoDetailError' /catalog/dataSources: get: tags: - Integrations summary: Get all available data sources description: This endpoint will allow you to get a list of all available data sources, including the credential fields required for each. operationId: getDataSources responses: '200': description: Successful operation content: application/json: schema: type: object properties: dataSources: type: array items: type: object properties: code: description: Unique code of the data source type: string example: michelin_connected_fleet label: description: Display name of the data source type: string example: Michelin Connected Fleet credentials: description: List of credential field names required to create an integration with this data source. Deprecated, use credentialsSchema instead. deprecated: true type: array items: type: string example: - username - password - customerId credentialsSchema: $ref: '#/components/schemas/CredentialsSchema' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations: get: tags: - Integrations summary: Get all available integrations description: This endpoint will allow you to get a list of all available integrations. operationId: getIntegrations responses: '200': description: Successful operation content: application/json: schema: type: object properties: integrations: type: array items: $ref: '#/components/schemas/GetIntegrationResponse' '204': $ref: '#/components/responses/204Success' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '500': $ref: '#/components/responses/500Error' post: tags: - Integrations summary: Create an integration description: This endpoint will allow you to create a new integration. operationId: addIntegration requestBody: description: More information about the required payload content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationBody' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/IntegrationIdResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '409': $ref: '#/components/responses/409Error' '422': $ref: '#/components/responses/422Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/{integrationId}: patch: tags: - Integrations summary: Update an integration description: This endpoint will allow you to update an existing integration. operationId: updateIntegration parameters: - name: integrationId in: path description: The unique identifier of the integration required: true schema: type: integer example: 123 requestBody: description: More information about the required payload content: application/json: schema: $ref: '#/components/schemas/PatchIntegrationBody' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PatchIntegrationResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '409': $ref: '#/components/responses/409Error' '422': $ref: '#/components/responses/422Error' '500': $ref: '#/components/responses/500Error' delete: tags: - Integrations summary: Delete an integration description: This endpoint will delete an existing integration. ⚠️ **Warning** This operation is irreversible. operationId: deleteIntegration parameters: - name: integrationId in: path description: The unique identifier of the integration to delete required: true schema: type: integer example: 123 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/IntegrationIdResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '409': $ref: '#/components/responses/409Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/{integrationId}/activate: post: tags: - Integrations summary: Activate an integration description: This endpoint will activate an existing integration. operationId: activateIntegration parameters: - name: integrationId in: path description: The unique identifier of the integration to activate required: true schema: type: integer example: 123 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/IntegrationIdResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/{integrationId}/deactivate: post: tags: - Integrations summary: Deactivate an integration description: This endpoint will deactivate an existing integration. operationId: deactivateIntegration parameters: - name: integrationId in: path description: The unique identifier of the integration to deactivate required: true schema: type: integer example: 123 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/IntegrationIdResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/oauth: post: tags: - OAuth summary: Start an OAuth session description: | Starts an OAuth session to create an integration with a data source that requires the user to log in on its own portal. Open the returned `oauthUrl` in the user's browser. The session expires after 15 minutes. See the [OAuth guide](https://docs.hiboo.io/guides/guides/managing-your-fleet/connecting-oauth-data-sources) for the full flow. Requires an organization admin. operationId: initOAuthSession requestBody: content: application/json: schema: $ref: '#/components/schemas/InitOAuthSessionBody' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OAuthSessionResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '409': $ref: '#/components/responses/409Error' '422': $ref: '#/components/responses/422Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/oauth/{sessionId}: get: tags: - OAuth summary: Get an OAuth session result description: | Returns the outcome of a completed OAuth session. Results are kept 5 minutes after completion; `404` before completion or after expiry. Requires an organization admin. operationId: getOAuthSessionResult parameters: - name: sessionId in: path description: The `sessionId` returned when starting the OAuth session required: true schema: type: string example: b3f1c2a4-5d6e-4f70-8a9b-0c1d2e3f4a5b responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OAuthSessionResult' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/{integrationId}/oauth: post: tags: - OAuth summary: Re-authenticate an integration via OAuth description: | Starts an OAuth session to renew the data source tokens of an existing integration, e.g. after the data source revoked them. Reuses the integration's data source and credentials. On success, the existing integration is reactivated. See the [OAuth guide](https://docs.hiboo.io/guides/guides/managing-your-fleet/connecting-oauth-data-sources). Requires an organization admin. operationId: initOAuthSessionForUpdate parameters: - name: integrationId in: path description: The unique identifier of the integration to re-authenticate required: true schema: type: integer example: 123 requestBody: content: application/json: schema: $ref: '#/components/schemas/OAuthRedirectBody' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OAuthSessionResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '422': $ref: '#/components/responses/422Error' '500': $ref: '#/components/responses/500Error' /catalog/integrations/{integrationId}/setup-links: get: tags: - OAuth summary: Get integration setup links description: | Returns data source pages where the user completes the integration setup, e.g. choosing which John Deere organizations are shared with Hiboo. Requires an organization admin. operationId: getIntegrationSetupLinks parameters: - name: integrationId in: path description: The unique identifier of the integration required: true schema: type: integer example: 123 - name: redirectUri in: query description: URL where the data source redirects the user's browser after the setup, when supported required: true schema: type: string format: uri example: https://app.example.com/integrations responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SetupLinksResponse' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '422': $ref: '#/components/responses/422Error' '500': $ref: '#/components/responses/500Error' /oauth/callback: get: tags: - OAuth summary: OAuth callback description: | Called by the data source's browser redirect, not by your application. Registered as `https://ingest.hiboo.io/oauth/callback`. Exchanges the authorization code for the data source tokens, creates or re-authenticates the integration, then redirects to the `redirectUri` given when starting the session, with `status=completed&integrationId=...&sessionId=...` or `status=error&sessionId=...`. operationId: handleOAuthCallback security: [] parameters: - name: code in: query description: Authorization code issued by the data source required: true schema: type: string - name: state in: query description: The `sessionId` of the OAuth session required: true schema: type: string responses: '200': description: HTML error page, when the session is unknown or expired content: text/html: schema: type: string '302': description: Redirect to the session's `redirectUri` headers: Location: schema: type: string example: https://app.example.com/integrations/oauth/callback?status=completed&integrationId=123&sessionId=b3f1c2a4-5d6e-4f70-8a9b-0c1d2e3f4a5b