openapi: 3.2.0 info: title: Paperless API v2 Parts API description: 'The Paperless Parts API provides access to your data, enabling developers to easily integrate Paperless Parts with third-party systems, such as Customer Relationship Management (CRM) and Enterprise Resource Planning (ERP) tools. The API is designed to support two primary use case. First, reading all information associated with a particular order or quote for import into another system. Second, managing customer data, either for an initial bulk import or for on-going synchronization with an external database. ## Authorization ## Requests are authorized via an API key. Administrators of a Paperless Parts account can generate an API Token which grants access to all of the endpoints documented here. The token obtained from the application must be added to the header of all requests using the key `\"Authorization\"` with the value `\"API-Token \"`, where `` is your Paperless Parts API Token. You can use the \"Execute\" button in an endpoint''s documentation on this page to try out the endpoint. This will send a request to the endpoint on the Paperless Parts server and display the result on this page. Before doing so, however, you''ll need to click on the ''Authorize'' button at the top of the screen, and in the \"Value\" field enter `\"API-Token \"`, where `` is your API token as described above. ## Overview ## The API endpoints are organized around REST. API calls should be made to the `https://api.paperlessparts.com` base domain. URLs are designed to clearly describe an entity or collection of entities. HTTP verbs typically describe whether entities are being read, created, modified, or deleted. Where applicable, request and response bodies are in JSON format. Standard HTTP response codes, in addition to error messages, are used to help explain request failures. ### Associations Many entities in the API data model are associated with other entities. As a guiding principle, `GET` requests that fetch data nest associated entities in the JSON response. However, when creating or modifying entities, a flat (non-nested) object must be provided, as explained in the documentation for each endpoint. Associations are specified when writing data by using entity IDs in fields ending in `_id`. For example, consider the relationship where a Company has many Customers. When fetching a Customer via a `GET` request, the associated Company will be nested as an object with key `company` in the response. When creating a Customer, the Company is specified via its integer id using the key `company_id`. ### Events Overview Events are a way of logging relevant actions that are taken within your account. For instance, when you create a new quote, Paperless Parts logs a `quote.created` event, and once you send that quote, we log another `quote.sent` event. These logs offer you a trail of data that you can use to keep integrations in sync. By polling for new events, you can maintain an up-to-date record of what actions Paperless Parts has initiated that your integration has not. For instance, you could poll for `part.interrogation_succeeded` events and send out a notification upon receiving one. ### HTTP Methods The API endpoints support different HTTP methods depending on whether records are being read, created, or updated. To read an entity, use `GET`. To create a new entity, use `POST`. To modifying an entity, use `PATCH`. Note, `PATCH` is used rather than `PUT` to indicate that entities can be partially updated. In other words, in general, if a field is omitted from a `PATCH` request, that field''s value will stay the same (rather than be set to `null`). All fields requiring values are required to be included in `POST` requests. > Note: Endpoints with a documented `PATCH` method can generally be used with a `PUT` method. The `PUT` is implemented as a partial update (as opposed to a replacement) and is supported for maximum compatibilty. For example, consider the `email` field on the Customer entity, which is required. All Customers must have a non-null `email`. When creating a Customer via `POST`, the request body must contain an `email` key and its value cannot be `null` (other validation applies to that field, as well, including a valid email format and a unique value). When editing a Customer via `PATCH` request, it is not necessary to include an `email` key in the request body. If `email` is omitted, the existing email address will not be changed. If you send a `PATCH` request with `email=null`, then you will receive an error response indicating that a value for `email` is required.' version: '2.0' termsOfService: https://www.paperlessparts.com/web-service-agreement/ contact: name: Paperless Parts url: https://www.paperlessparts.com email: support@paperlessparts.com servers: - url: '{url}/{version}' variables: url: default: https://api.paperlessparts.com version: default: v2 security: - app_id: [] tags: - name: Parts description: Endpoints for managing Parts paths: /parts/public/parts: get: summary: 'Get list of parts ATTENTION: Currently only manual parts!' description: Returns a list of parts. The parts are returned 20 results at a time and can be iterated over by using the page parameter. operationId: ListParts parameters: - in: query name: search schema: type: string required: false description: Value used to search against the part name or part number - in: query name: page schema: type: string required: false description: The page of results to return. - in: query name: type schema: type: string required: false description: The type of the part (Assembled, Manufacture, or Purchased). - in: query name: is_root_part schema: type: boolean required: false description: Only return root parts tags: - Parts responses: 200: description: Successful response content: application/json: schema: type: array items: type: object properties: uuid: type: string example: 3ec5051e-9d2d-4ea4-b903-abd9b6aa3448 description: The Part's uuid filename: type: string example: arch_b.step description: The filename for the Part part_number: type: string example: 12515 description: The Part's part number revision: type: string example: B description: The Part's revision is_root_part: type: boolean example: true description: Boolean for if the part is the root part type: type: - string - 'null' example: Manufactured description: The type of the Part (Assembled, Manufacture, or Purchased). 404: description: Not found response content: text/plain: schema: title: No Parts found type: string example: 'Error: Not Found' /parts/public/geometric_part: post: summary: Upload geometric part operationId: CreateGeometricPart tags: - Parts requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The part file to upload (required). interrogations: type: array description: The types of interrogations to perform. Options are additive, mill3, casting, sheet_metal, lathe, and wire_edm example: - additive - mill3 items: type: string thickness: type: - number - 'null' example: 4.3656 description: The thickness of the part units: type: - string - 'null' example: mm description: The unit for part measurements responses: 201: description: Successful response content: application/json: schema: $ref: '#/components/schemas/Part' /parts/public/get_root_part/{partUuid}: get: summary: Get the details for a part tags: - Parts parameters: - $ref: '#/components/parameters/partUuid' responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/Part' 404: description: Not found response content: text/plain: schema: title: No Parts found type: string example: 'Error: Not Found' patch: summary: Update the details for a part tags: - Parts parameters: - $ref: '#/components/parameters/partUuid' requestBody: required: true content: application/json: schema: type: object properties: units: type: - string - 'null' example: mm description: The unit for part measurements custom_attributes: type: object description: Custom attributes on this part, as a map from attribute name to attribute data. The object supplied here will be merged into the existing custom attribute values. To remove a custom attribute, supply null for its data rather than an object. additionalProperties: type: object properties: value: oneOf: - type: string - type: number - type: boolean description: The value of the attribute. type: type: string enum: - string - number - boolean description: The type of the attribute. responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/Part' 404: description: Not found response content: text/plain: schema: title: No Parts found type: string example: 'Error: Not Found' /parts/public/manual_part: post: summary: Create a manual Part operationId: CreateManualPart tags: - Parts requestBody: required: true content: application/json: schema: type: object properties: area: type: - number - 'null' example: 26451.058 description: The area of the part filename: type: - string - 'null' example: arch_b.step description: The filename or name of the part part_number: type: - string - 'null' example: 12515 description: The Part's part number part_master_uuid: type: - string - 'null' example: 3be4436a-f9c9-4a12-8c4f-d3dbc49838e7 description: The uuid of the Part's Part Master purchased_component_id: type: - integer - 'null' example: 1256 description: The id of the purchased component material_id: type: - integer - 'null' example: 50 description: The id for the material of the part revision: type: - string - 'null' example: B description: The Part's revision size_x: type: - number - 'null' example: 112.77 description: The size for the x dimension of the part size_y: type: - number - 'null' example: 88.06 description: The size for the y dimensions of the part size_z: type: - number - 'null' example: 22.86 description: The size for the z dimension of the part thickness: type: - number - 'null' example: 4.3656 description: The thicknees of the part type: type: - string - 'null' example: Manufactured description: The type of the Part (Assembled, Manufacture, or Purchased). units: type: - string - 'null' example: mm description: The unit for part measurements responses: 201: description: Successful response content: application/json: schema: $ref: '#/components/schemas/Part' /parts/public/manual_assembly: post: summary: Create a manual assembly operationId: CreateManualAssembly tags: - Parts requestBody: required: true content: application/json: schema: type: array items: type: object properties: temp_id: type: number example: -1 description: A negative number representing a temporary id that is used to build the assembly structure area: type: - number - 'null' example: 26451.058 description: The area of the part filename: type: - string - 'null' example: arch_b.step description: The filename or name of the part purchased_component_id: type: - integer - 'null' example: 1256 description: The id of the purchased component part_number: type: - string - 'null' example: 12515 description: The Part's part number part_master_uuid: type: - string - 'null' example: 3be4436a-f9c9-4a12-8c4f-d3dbc49838e7 description: The uuid of the Part's Part Master material_id: type: - integer - 'null' example: 50 description: The id for the material of the part revision: type: - string - 'null' example: B description: The Part's revision size_x: type: - number - 'null' example: 112.77 description: The size for the x dimension of the part size_y: type: - number - 'null' example: 88.06 description: The size for the y dimensions of the part size_z: type: - number - 'null' example: 22.86 description: The size for the z dimension of the part thickness: type: - number - 'null' example: 4.3656 description: The thicknees of the part type: type: - string - 'null' example: Manufactured description: The type of the Part (Assembled, Manufacture, or Purchased). units: type: - string - 'null' example: mm description: The unit for part measurements nodes: type: array items: type: object properties: child: type: number example: -2 description: The temporary id of the child part count: type: number example: 1 description: The number of times the child occurs responses: 201: description: Successful response content: application/json: schema: $ref: '#/components/schemas/Assembly' /parts/public/{partUuid}/status: get: summary: Get the status of a part parameters: - $ref: '#/components/parameters/partUuid' operationId: GetPartStatus tags: - Parts responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/PartStatus' /parts/public/part_files/{uuid}/flat_pattern_dxf: get: summary: Get flat pattern DXF download link and warnings description: Returns an authenticated download URL for the flat pattern DXF file along with flat pattern origin information and warning messages. The flat pattern DXF file must be available for the part file. parameters: - name: uuid in: path description: The part file UUID required: true schema: $ref: '#/components/schemas/Uuid' operationId: GetFlatPatternDXFDownload tags: - Parts responses: 200: description: Successful response content: application/json: schema: type: object properties: download_url: type: string description: The authenticated download URL for the flat pattern DXF file example: https://api.paperlessparts.com/api/v2/parts/public/part_files/3ec5051e-9d2d-4ea4-b903-abd9b6aa3448/flat_pattern_dxf?token=... flat_pattern_origin: type: - string - 'null' description: 'The origin type of the flat pattern. Possible values are: ''3D-unfolded'', ''3D-flat'', ''PDF-vectorized'', ''DXF-edited'', ''DXF-uploaded'', ''DWG-edited'', ''DWG-uploaded''' warning_message: type: - string - 'null' description: Warning message about the flat pattern, if applicable 404: description: Not found response content: text/plain: schema: title: Flat pattern DXF not available type: string example: Flat pattern DXF file not available for this part. components: schemas: PartStatus: type: object properties: processing: type: string example: in_progress description: 'The status of the part''s geometric processing: in_progress, failed, or finished' interrogation: type: string example: in_progress description: 'The status of the part''s interrogation: in_progress, failed, or finished' Assembly: type: object properties: parts: type: array items: $ref: '#/components/schemas/Part' nodes: type: array items: $ref: '#/components/schemas/PartNode' PartNode: type: object properties: parent_uuid: type: string example: 2f0e5724-42fe-47ae-8233-7a902ef70346 description: The uuid of the parent part child_uuid: type: string example: 4b4d3e8c-cfe2-4b3c-bd6f-792c3335f1fc description: The uuid of the child part count: type: integer example: 1 description: The number of times this node occurs Uuid: type: string description: Unique identifier example: 2f0e5724-42fe-47ae-8233-7a902ef70346 Part: type: object properties: area_mm: type: - number - 'null' example: 26451.058 description: The area of the part, expressed in mm. Will be null if the part is export controlled. description: type: string description: The part description filename: type: string example: arch_b.step description: The filename or name of the part is_root_part: type: boolean description: Indicates whether this is the root part in an assembly. For non-assembly parts, this will always be true. is_from_external_system: type: boolean description: Indicates whether the part is being mirrored from an external system. If true, this part will not show up in the part library. part_number: type: string example: 12515 description: The Part's part number part_master_uuid: type: string example: 3be4436a-f9c9-4a12-8c4f-d3dbc49838e7 description: The uuid of the Part's Part Master material_id: type: integer example: 50 description: The id for the material of the part revision: type: string example: B description: The Part's revision size_x: type: - number - 'null' example: 112.77 description: The size for the x dimension of the part. Will be null if the part is export controlled. size_y: type: - number - 'null' example: 88.06 description: The size for the y dimensions of the part. Will be null if the part is export controlled. size_z: type: - number - 'null' example: 22.86 description: The size for the z dimension of the part. Will be null if the part is export controlled. size_x_mm: type: - number - 'null' description: The size for the x dimension of the part, expressed in mm. Will be null if the part is export controlled. size_y_mm: type: - number - 'null' description: The size for the y dimension of the part, expressed in mm. Will be null if the part is export controlled. size_z_mm: type: - number - 'null' description: The size for the z dimension of the part, expressed in mm. Will be null if the part is export controlled. thickness: type: - number - 'null' example: 4.3656 description: The thicknees of the part. Will be null if the part is export controlled. thumbnail_url: type: - string - 'null' description: The URL from which to download the thumbnail image. Will be null if the part is export controlled. type: type: string example: Manufactured description: The type of the Part uuid: type: string example: 2f0e5724-42fe-47ae-8233-7a902ef70346 units: type: string example: mm description: The unit for part measurements thickness_units: type: string example: mm volume_mm: type: - number - 'null' description: The volume of the part, expressed in mm. Will be null if the part is export controlled. custom_attributes: type: object description: Custom attributes on the part, as a map from attribute name to data additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the custom attribute value: oneOf: - type: string - type: number - type: boolean description: The value of the custom attribute parameters: partUuid: name: partUuid in: path description: The part UUID required: true schema: $ref: '#/components/schemas/Uuid' securitySchemes: app_id: type: apiKey description: API key to authorize requests. name: Authorization in: header