OpenAPI Specification
openapi: 3.0.0
info:
description: Welcome to the MaintainX API documentation!<br/><br/>You can use the MaintainX API to programmatically interact with all the entities in MaintainX. Use it to retrieve and manage data of Work Orders, Work Requests, Assets, and more!<br/><br/>To get started, in your MaintainX account go to <a href="https://app.getmaintainx.com/settings/integrations/apiKeys">"Settings > Integrations"</a> and click "+ New Key" button to generate a new Rest API key.<br/><br/><b>Missing something?</b><br/>Don't hesitate to reach out <a href="mailto:support@getmaintainx.com">support@getmaintainx.com</a><br/><br/>
version: '1'
title: MaintainX Asset Criticalities Assets API
contact:
url: https://www.getmaintainx.com/
name: Support
email: support@getmaintainx.com
x-logo:
url: https://maintainx-static.s3-us-west-2.amazonaws.com/img/default-org-logo.png
backgroundColor: '#FFFFFF'
altText: MaintainX logo
servers:
- url: https://api.getmaintainx.com/v1
description: Endpoint
security:
- Bearer: []
tags:
- name: Assets
description: Operations on Assets
x-traitTag: false
paths:
/assets:
post:
summary: Create new asset
requestBody:
description: Asset to create
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: Forklift
description:
type: string
nullable: true
example: Forklift that is used to to move heavy equipments around the warehouse
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
criticalityId:
type: integer
nullable: true
example: 150
description: ID of the criticality of the asset
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent asset
locationId:
type: integer
nullable: true
example: 852
description: ID of the location where the asset is located
teamIds:
type: array
items:
type: integer
description: List of teams responsible for the asset
example:
- 123
- 456
assetTypes:
type: array
items:
type: string
example:
- manual
- tool
description: List of asset types
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "My Custom Field")'
additionalProperties:
type: string
example:
My Custom Field: '000000000'
vendorIds:
type: array
description: Vendor IDs
items:
type: number
example: 1
serialNumber:
type: string
nullable: true
description: Serial number of the asset
example: 000123ABC
depreciation:
type: object
nullable: true
description: Depreciation information of the asset
properties:
id:
type: number
example: 42
description: Global ID of the asset depreciation.
accumulatedDepreciation:
type: number
description: Accumulated depreciation of the asset.
format: decimal
nullable: true
example: '5000.00'
annualDepreciation:
type: number
description: Annual depreciation of the asset.
format: decimal
nullable: true
example: '1000.00'
depreciationStartDate:
type: string
description: Date at which the asset depreciation started.
format: date-time
nullable: true
example: '2022-01-01T00:00:00.000Z'
currentBookValue:
type: number
description: Current book value of the asset.
format: decimal
nullable: true
example: '7500.00'
purchasePrice:
type: number
description: Purchase price of the asset.
format: decimal
nullable: true
example: '12500.00'
purchaseDate:
type: string
description: Date & time at which the asset was purchased.
format: date-time
nullable: true
example: '2022-01-01T00:00:00.000Z'
salvageValue:
type: number
description: Salvage value of the asset.
format: decimal
nullable: true
example: '2500.00'
usefulLifeYears:
type: number
description: Useful life of the asset in years.
format: decimal
nullable: true
example: 10
yearsDepreciated:
type: number
description: Years depreciated of the asset.
format: decimal
nullable: true
example: 5
createdAt:
type: string
description: Date & time at which the asset depreciation was created.
format: date-time
example: '2022-01-01T00:00:00.000Z'
nullable: true
archivedAt:
type: string
format: date-time
description: Date & time at which the asset depreciation was archived.
example: '2022-01-01T00:00:00.000Z'
nullable: true
manufacturer:
type: object
nullable: true
description: Manufacturer information for the asset. Set to null to clear manufacturer and model.
properties:
id:
type: integer
nullable: true
description: ID of an existing manufacturer. If provided, the manufacturer must be either global or belong to your organization. If not provided, the manufacturer will be looked up by name.
example: 123
name:
type: string
nullable: true
description: Name of the manufacturer. Required if id is not provided. When searching by name, the manufacturer must be either global or belong to your organization.
example: ACME Corporation
model:
type: object
nullable: true
description: Model information for the asset. Set to null to clear model.
properties:
id:
type: integer
nullable: true
description: ID of an existing model. If provided, the model must be linked to the specified manufacturer and be either global or belong to your organization. If not provided, the model will be looked up by name.
example: 456
name:
type: string
nullable: true
description: Name of the model. Required if id is not provided. When searching by name, the model must be linked to the specified manufacturer and be either global or belong to your organization.
example: X-2000
responses:
'201':
description: Successfully created asset
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
example: 963
description: Global ID of the asset
'400':
description: OrganizationId was not provided
content:
application/json:
schema:
type: object
required:
- errors
example:
errors:
- error: Missing x-organization-id header.
properties:
errors:
type: array
items:
type: object
required:
- error
properties:
error:
type: string
fieldPath:
nullable: true
type: string
fieldValue:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
'401':
$ref: '#/components/responses/UnauthorizedError'
tags:
- Assets
parameters:
- schema:
type: boolean
description: Set `skipWebhook=true`, `skipWebhook=1` or `skipWebhook=yes` to skip all webhooks upon successful operation on the endpoint. [Learn more about webhooks](#tag/Subscriptions-and-Webhooks)
name: skipWebhook
in: query
required: false
- schema:
type: integer
description: Required if using a multi organizations token
name: x-organization-id
in: header
required: false
example: '1'
get:
summary: List assets
description: Endpoint used to list asset resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Assets returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: locationId
schema:
type: integer
description: Will only show assets that are related to the location
in: query
- name: manufacturer
schema:
type: array
items:
type: string
description: Filter assets by their manufacturer name
in: query
- name: model
schema:
type: array
items:
type: string
description: Filter assets by their manufacturer model name
in: query
- name: updatedAt[gte]
schema:
type: string
format: date-time
description: Return records whose updatedAt is at or after this ISO 8601 date-time (UTC).
example: '2024-01-01T00:00:00.000Z'
in: query
- name: updatedAt[lte]
schema:
type: string
format: date-time
description: Return records whose updatedAt is at or before this ISO 8601 date-time (UTC).
example: '2024-12-31T23:59:59.999Z'
in: query
- name: createdAt[gte]
schema:
type: string
format: date-time
description: Return records whose createdAt is at or after this ISO 8601 date-time (UTC).
example: '2024-01-01T00:00:00.000Z'
in: query
- name: createdAt[lte]
schema:
type: string
format: date-time
description: Return records whose createdAt is at or before this ISO 8601 date-time (UTC).
example: '2024-12-31T23:59:59.999Z'
in: query
- name: customFieldName
schema:
type: array
items:
type: string
description: "Filter assets by custom field value. Your query parameter should be your custom field name. (ie: To filter by a custom field named \"Industry\" with the value \"Construction\", you would do this \"/assets?Industry=Construction\").\n <br><br>Adding multiple instance of the same custom field act as an <code>OR</code> and adding a different custom field act as an <code>AND</code>. (ie: To filter by a custom field named <code>Industry</code> with the value <code>Construction</code> OR <code>Transportation</code> AND the custom field <code>Manufacturer</code> with the value <code>ACME</code>, you would do this <code>/assets?Industry=Construction&Industry=Transportation&Manufacturer=ACME</code>).\n <br><br>If your custom field label is the same as a reserved query parameter such as <code>limit</code>, <code>sort</code>, <code>expand</code>, etc, you can add <code>__c</code> to your custom field filtering (ie: To filter by a custom field named <code>limit</code> with the value <code>ten</code>, you would do this <code>/assets?limit__c=ten</code>).\n <br><br>Note that your custom field needs to be created beforehand. Only number and single line text custom field types are supported."
in: query
- in: query
name: sort
schema:
description: 'Attribute on which to sort the list. (for descending order, prefix attribute with ''-''). '
type: string
enum:
- id
- createdAt
- updatedAt
- -id
- -createdAt
- -updatedAt
- in: query
name: expand
schema:
title: Expand specific fields in the request
description: 'To expand multiple fields: `expand=barcode&expand=team_ids`'
type: array
items:
type: string
enum:
- barcode
- team_ids
- asset_types
- extra_fields
- vendor_ids
- depreciation
- status
- manufacturer
- model
- schema:
type: integer
description: Required if using a multi organizations token
name: x-organization-id
in: header
required: false
example: '1'
- schema:
type: string
description: Required if using a multi organizations token and doing an operation on resources from multiple organizations. This is mutually exclusive with the x-organization-id header (use one or the other).
name: x-organization-ids
in: header
required: false
example: 1,2,3
responses:
'200':
description: Successfully fetched Assets list
content:
application/json:
schema:
type: object
required:
- assets
properties:
assets:
type: array
items:
type: object
required:
- id
- name
- description
- parentId
- criticalityId
- locationId
- serialNumber
- createdAt
- updatedAt
- creatorId
properties:
id:
type: integer
example: 963
description: Global ID of the asset
name:
type: string
example: Forklift
description:
type: string
nullable: true
example: Forklift that is used to to move heavy equipments around the warehouse
parentId:
type: integer
nullable: true
example: 852
description: ID of the parent asset
criticalityId:
type: integer
nullable: true
example: 150
description: ID of the criticality of the asset
locationId:
type: integer
nullable: true
example: 852
description: ID of the location where the asset is located
serialNumber:
type: string
nullable: true
description: Serial number of the asset
example: 000123ABC
createdAt:
type: string
format: date-time
description: Date & time at which the asset was created
example: '2022-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the asset was last updated. This doesn't include comments
example: '2022-01-01T00:00:00.000Z'
creatorId:
type: integer
nullable: true
example: 851
description: ID of the asset creator
organizationId:
type: integer
example: 1
description: ID of the organization that owns this resource
barcode:
type: string
nullable: false
example: BWFPBNRHAW54CG
description: String encoded barcode (expand with query parameter)
teamIds:
type: array
items:
type: integer
description: List of teams responsible for the asset (expand with query parameter)
example:
- 123
- 456
nullable: false
assetTypes:
type: array
items:
type: string
example:
- manual
- tool
description: List of asset types (expand with query parameter)
nullable: false
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "My Custom Field") (expand with query parameter)'
additionalProperties:
type: string
example:
My Custom Field: '000000000'
nullable: false
vendorIds:
type: array
description: Vendor IDs (expand with query parameter)
items:
type: number
example: 1
nullable: false
depreciation:
type: object
nullable: false
description: Depreciation information of the asset (expand with query parameter)
properties:
id:
type: number
example: 42
description: Global ID of the asset depreciation.
accumulatedDepreciation:
type: number
description: Accumulated depreciation of the asset.
format: decimal
nullable: true
example: '5000.00'
annualDepreciation:
type: number
description: Annual depreciation of the asset.
format: decimal
nullable: true
example: '1000.00'
depreciationStartDate:
type: string
description: Date at which the asset depreciation started.
format: date-time
nullable: true
example: '2022-01-01T00:00:00.000Z'
currentBookValue:
type: number
description: Current book value of the asset.
format: decimal
nullable: true
example: '7500.00'
purchasePrice:
type: number
description: Purchase price of the asset.
format: decimal
nullable: true
example: '12500.00'
purchaseDate:
type: string
description: Date & time at which the asset was purchased.
format: date-time
nullable: true
example: '2022-01-01T00:00:00.000Z'
salvageValue:
type: number
description: Salvage value of the asset.
format: decimal
nullable: true
example: '2500.00'
usefulLifeYears:
type: number
description: Useful life of the asset in years.
format: decimal
nullable: true
example: 10
yearsDepreciated:
type: number
description: Years depreciated of the asset.
format: decimal
nullable: true
example: 5
createdAt:
type: string
description: Date & time at which the asset depreciation was created.
format: date-time
example: '2022-01-01T00:00:00.000Z'
nullable: true
archivedAt:
type: string
format: date-time
description: Date & time at which the asset depreciation was archived.
example: '2022-01-01T00:00:00.000Z'
nullable: true
status:
type: object
nullable: false
description: Status information of the asset (expand with query parameter)
properties:
id:
type: number
example: 42
description: Global ID of the asset status.
status:
type: string
example: OFFLINE
description: Asset status value.
enum:
- IGNORE
- OFFLINE
- ONLINE
downtimeType:
type: string
nullable: true
example: PLANNED
enum:
- PLANNED
- UNPLANNED
startedAt:
type: string
format: date-time
example: '2022-01-01T12:34:56.123Z'
description: Asset status effective start date.
endedAt:
type: string
format: date-time
example: '2022-01-01T12:34:56.123Z'
description: Asset status effective end date.
nullable: true
description:
type: string
example: Overheated - needs servicing.
nullable: true
createdAt:
type: string
format: date-time
example: '2022-01-01T12:34:56.123Z'
readOnly: true
description: Date & time at which the asset status was created.
updatedAt:
type: string
format: date-time
example: '2022-01-01T12:34:56.123Z'
readOnly: true
description: Date & time at which the asset status was last updated.
deletedAt:
type: string
format: date-time
example: '2022-01-01T12:34:56.123Z'
readOnly: true
description: Date & time at which the asset status was deleted.
nullable: true
customStatus:
type: object
required:
- label
properties:
id:
type: number
example: Global ID of the custom asset status.
label:
type: string
example: Decommissioned
createdAt:
type: string
format: date-time
description: Date & time at which the asset custom status was created.
example: '2022-01-01T12:34:56.123Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the asset custom status was last updated.
example: '2022-01-01T12:34:56.123Z'
deletedAt:
type: string
nullable: true
description: Date at which the asset custom status was deleted.
format: date-time
example: '2022-01-01T12:34:56.123Z'
description: Custom status assigned to asset.
nullable: true
manufacturer:
type: string
nullable: false
description: Name of the manufacturer of the asset (expand with query parameter)
example: Manufacturer
model:
type: string
nullable: false
description: Name of the model of the asset (expand with query parameter)
example: Model
nextCursor:
description: The cursor to retrieve the next page of Assets.
type: string
nullable: true
nextPageUrl:
description: Path with query parameters that can be used to retrieve the next page of Assets.
type: string
nullable: true
'400':
description: Error with query
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
description: Description of error
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
tags:
- Assets
/assets/{id}:
get:
summary: Get asset
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the asset
example: '1'
responses:
'200':
description: Successfully retrieved asset's information
content:
application/json:
schema:
type: object
required:
- asset
properties:
asset:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 963
description: Global ID of the asset
name:
type: string
example: Forklift
globalUuid:
type: string
nullable: true
description: Global unique identifier of the asset used to identify assets as they are being transferred
example: e2eb31cb-dd28-495a-92dd-6a435514f5ae
currentOwnerId:
type: number
description: Organization id that currently has the active version of this asset
example: 1
barcode:
type: string
nullable: true
example: BWFPBNRHAW54CG
description: String encoded barcode
description:
type: string
nullable: true
example: Forklift that is used to to move heavy equipments around the warehouse
criticalityId:
type: integer
nullable: true
example: 150
description: ID of the criticality of the asset
# --- truncated at 32 KB (290 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-assets-api-openapi.yml