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 Parts 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: Parts
description: Operations on Parts
x-traitTag: false
paths:
/parts:
post:
summary: Create new part
requestBody:
description: Part to create
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: Locknut - 1/8
description:
type: string
nullable: true
example: ''
area:
type: string
example: tool room
nullable: true
description: 'Area of the part. Deprecated: Use new field inside `locations`. Will cause error if both fields are sent.'
deprecated: true
unitCost:
type: integer
description: Cost in cents. For example, for $1.20, put 120.
example: 120
nullable: true
availableQuantity:
type: integer
description: 'Total quantity currently in stock. Deprecated: Use new field inside `locations`. Will cause error if both fields are sent.'
example: 10
deprecated: true
minimumQuantity:
type: integer
description: 'Total minimum quantity before you should restock. Deprecated: Use new field inside `locations`. Will cause error if both fields are sent.'
example: 5
deprecated: true
barcode:
type: string
nullable: true
example: bWFpbnRhaW54Cg==
description: String encoded barcode
locationId:
type: integer
nullable: true
example: 852
description: 'ID of the location where the part is located. Deprecated: Use new field inside `locations`. Will cause error if both fields are sent.'
deprecated: true
locations:
type: array
items:
type: object
required:
- locationId
properties:
locationId:
type: integer
example: 852
description: ID of the location where the part is located
availableQuantity:
type: integer
description: Quantity currently in stock
example: 10
minimumQuantity:
type: integer
description: Minimum quantity before you should restock
example: 5
nullable: true
maximumQuantity:
type: integer
nullable: true
example: 100
description: Maximum quantity you want to stock. Must be greater than or equal to minimumQuantity.
area:
type: string
example: tool room
nullable: true
description: Detailed list of locations where the part is stored, including properties such as available quantity, minimum quantity, reserved quantity, and area within each location.
partTypes:
type: array
items:
type: string
description: List of part types
assetIds:
type: array
items:
type: integer
example:
- 12
- 4561
description: List of asset IDs
teamIds:
type: array
items:
type: integer
example:
- 1
- 4
description: List of team IDs in charge of the part
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Part Number")'
additionalProperties:
type: string
example:
Part Number: '000000000'
vendors:
type: array
description: List of vendors of the part
items:
type: object
properties:
vendorId:
type: integer
example: '1'
description: Id of the vendor
partNumber:
type: string
example: XC230
description: Part number given to the part by this vendor
committedQuantities:
type: object
description: Quantities of the part currently committed to work orders, broken down by stage.
properties:
kitted:
type: integer
description: Quantity of parts that have been kitted for work orders
example: 5
reserved:
type: integer
description: Quantity of parts reserved for work orders
example: 3
staged:
type: integer
description: Quantity of parts that have been staged for work orders
example: 2
assignedQuantity:
type: integer
description: Total quantity currently assigned to work orders across all stages.
example: 10
vendorIds:
type: array
items:
type: integer
example:
- 23
- 56
description: 'List of vendor IDs. Deprecated: Use the `vendorId` field inside `vendors`.'
deprecated: true
responses:
'201':
description: Successfully created part
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
example: 123456
description: Global ID of the part
'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:
- Parts
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 parts
description: Endpoint used to list part resources
parameters:
- name: cursor
in: query
schema:
description: Last pagination reference
type: string
- name: limit
in: query
schema:
description: max number of Parts returned
type: integer
minimum: 1
maximum: 200
default: 100
- name: partNumber
schema:
type: array
description: Will only show parts that have a vendor with this part number associated to them.
items:
type: string
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 parts 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 \"/parts?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>/parts?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>/parts?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=extra_fields&expand=vendors`'
type: array
items:
type: string
enum:
- extra_fields
- vendors
- 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 Parts list
content:
application/json:
schema:
type: object
required:
- parts
properties:
parts:
type: array
items:
type: object
required:
- id
- name
- description
- barcode
- locationId
- locations
- area
- unitCost
- availableQuantity
- minimumQuantity
- orderedQuantity
- reservedQuantity
- partTypes
- createdAt
- updatedAt
properties:
id:
type: integer
example: 123456
description: Global ID of the part
name:
type: string
example: Locknut - 1/8
description:
type: string
nullable: true
example: ''
barcode:
type: string
nullable: true
example: bWFpbnRhaW54Cg==
description: String encoded barcode
locationId:
type: integer
nullable: true
example: 852
description: 'ID of the location where the part is located. Deprecated: for Parts with multiple locations, use the new field in `locations`'
deprecated: true
locations:
type: array
items:
type: object
required:
- locationId
properties:
locationId:
type: integer
example: 852
description: ID of the location where the part is located
availableQuantity:
type: integer
description: Quantity currently in stock
example: 10
minimumQuantity:
type: integer
description: Minimum quantity before you should restock
example: 5
nullable: true
maximumQuantity:
type: integer
nullable: true
example: 100
description: Maximum quantity you want to stock. Must be greater than or equal to minimumQuantity.
area:
type: string
example: tool room
nullable: true
reservedQuantity:
type: integer
description: 'Quantity currently reserved for work orders. Deprecated: Use `committedQuantities.reserved` instead.'
example: 10
nullable: true
deprecated: true
committedQuantities:
type: object
description: Quantities of the part currently committed to work orders, broken down by stage.
properties:
kitted:
type: integer
description: Quantity of parts that have been kitted for work orders
example: 5
reserved:
type: integer
description: Quantity of parts reserved for work orders
example: 3
staged:
type: integer
description: Quantity of parts that have been staged for work orders
example: 2
assignedQuantity:
type: integer
description: Quantity currently assigned to work orders at this location
example: 5
description: Detailed list of locations where the part is stored, including properties such as available quantity, minimum quantity, reserved quantity, and area within each location.
area:
type: string
example: tool room
nullable: true
description: 'Area of the part. Deprecated: for Parts with multiple locations, use the new field in `locations`'
deprecated: true
unitCost:
type: integer
description: Cost in cents. For example, for $1.20, put 120.
example: 120
nullable: true
availableQuantity:
type: integer
description: 'Total quantity currently in stock. If your plan includes multi-location parts, this is the quantity across all part locations. Deprecated: Use `inStockQuantity` instead.'
example: 10
deprecated: true
minimumQuantity:
type: integer
description: Total minimum quantity before you should restock. If your plan includes multi-location parts, this is the quantity across all part locations.
example: 5
orderedQuantity:
type: integer
description: Total quantity currently on order from purchase orders. If your plan includes multi-location parts, this is the quantity across all part locations.
example: 15
reservedQuantity:
type: integer
description: 'Total quantity currently reserved for work orders. If your plan includes multi-location parts, this is the quantity across all part locations. Deprecated: Use `committedQuantities.reserved` instead.'
example: 3
deprecated: true
partTypes:
type: array
items:
type: string
description: List of part types
createdAt:
type: string
format: date-time
description: Date & time at which the part was created
example: '2022-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Date & time at which the part was last updated. This doesn't include comments
example: '2022-01-01T00:00:00.000Z'
inStockQuantity:
type: integer
description: Total quantity currently in stock. If your plan includes multi-location parts, this is the quantity across all part locations.
example: 10
committedQuantities:
type: object
description: Quantities of the part currently committed to work orders, broken down by stage.
properties:
kitted:
type: integer
description: Quantity of parts that have been kitted for work orders
example: 5
reserved:
type: integer
description: Quantity of parts reserved for work orders
example: 3
staged:
type: integer
description: Quantity of parts that have been staged for work orders
example: 2
assignedQuantity:
type: integer
description: Total quantity currently assigned to work orders across all stages.
example: 10
maximumQuantity:
type: integer
nullable: true
example: 100
description: Total maximum quantity to keep in stock. Null when no part location has a max set. If your plan includes multi-location parts, this is the quantity across all part locations.
organizationId:
type: integer
example: 1
description: ID of the organization that owns this resource
extraFields:
type: object
description: 'Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Part Number") (expand with query parameter)'
additionalProperties:
type: string
example:
Part Number: '000000000'
nullable: false
vendors:
type: array
description: List of vendors of the part (expand with query parameter)
items:
type: object
properties:
vendorId:
type: integer
example: '1'
description: Id of the vendor
partNumber:
type: string
example: XC230
description: Part number given to the part by this vendor
nullable: false
nextCursor:
description: The cursor to retrieve the next page of Parts.
type: string
nullable: true
nextPageUrl:
description: Path with query parameters that can be used to retrieve the next page of Parts.
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:
- Parts
/parts/{id}:
get:
summary: Get part
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: ID of the part
example: '1'
responses:
'200':
description: Successfully retrieved part's information
content:
application/json:
schema:
type: object
required:
- part
properties:
part:
type: object
required:
- id
- name
- updatedAt
- createdAt
properties:
id:
type: integer
example: 123456
description: Global ID of the part
name:
type: string
example: Locknut - 1/8
description:
type: string
nullable: true
example: ''
area:
type: string
example: tool room
nullable: true
description: 'Area of the part. Deprecated: for Parts with multiple locations, use the new field in `locations`'
deprecated: true
unitCost:
type: integer
description: Cost in cents. For example, for $1.20, put 120.
example: 120
nullable: true
availableQuantity:
type: integer
description: 'Total quantity currently in stock. If your plan includes multi-location parts, this is the quantity across all part locations. Deprecated: Use `inStockQuantity` instead.'
example: 10
deprecated: true
inStockQuantity:
type: integer
description: Total quantity currently in stock. If your plan includes multi-location parts, this is the quantity across all part locations.
example: 10
minimumQuantity:
type: integer
description: Total minimum quantity before you should restock. If your plan includes multi-location parts, this is the quantity across all part locations.
example: 5
barcode:
type: string
nullable: true
example: bWFpbnRhaW54Cg==
description: String encoded barcode
locationId:
type: integer
nullable: true
example: 852
description: 'ID of the location where the part is located. Deprecated: for Parts with multiple locations, use the new field in `locations`'
deprecated: true
locations:
type: array
items:
type: object
required:
- locationId
properties:
locationId:
type: integer
example: 852
description: ID of the location where the part is located
availableQuantity:
type: integer
description: Quantity currently in stock
example: 10
minimumQuantity:
type: integer
description: Minimum quantity before you should restock
example: 5
nullable: true
maximumQuantity:
type: integer
nullable: true
example: 100
description: Maximum quantity you want to stock. Must be greater than or equal to minimumQuantity.
area:
type: string
example: tool room
nullable: true
reservedQuantity:
type: integer
description: 'Quantity currently reserved for work orders. Deprecated: Use `committedQuantities.reserved` instead.'
example: 10
nullable: true
deprecated: true
committedQuantities:
type: object
description: Quantities of the part currently committed to work orders, broken down by stage.
properties:
kitted:
type: integer
description: Quantity of parts that have been kitted for work orders
example: 5
reserved:
type: integer
description: Quantity of parts reserved for work orders
example: 3
staged:
type: integer
description: Quantity of parts that have been staged for work orders
example: 2
assignedQuantity:
type: integer
description: Quantity currently assigned to work orders at this location
example: 5
description: Detailed list of locations where the part is stored, including properties such as available quantity, minimum quantity, reserved quantity, and area within each location.
partTypes:
type: array
items:
type: string
description: List of part types
assetIds:
type: array
items:
type: integer
example:
# --- truncated at 32 KB (279 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maintainx/refs/heads/main/openapi/maintainx-parts-api-openapi.yml