API Documentation

The API is intended for interfacing other software with PartsBox, to allow integration and automation.

WARNING: this is the initial release and it should be considered as "beta" quality. It is very much subject to change, in fact it is absolutely certain that there will be important changes before it stabilizes. If you are looking for stability, please wait for an LTS (Long-Term Support) API release announcement. Please also read the "Warnings and pitfalls" section.

Example

A quick example is the best way to show what you can expect from the API.

Request:

curl -X POST \
  -d '{"part/id": "1pbvre0cfg4f58azmvsgetasxq"}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: APIKey partsboxapi_412k7ab40agdsa0tgfbcjbc46m8c728c1fd1a33728687f520a43dd16df03801f' \
  https://api.partsbox.com/api/1/part/get

Response:

{
  "data": {"part/id": "1pbqre1cfg4f59azmvsyftqsxe",
           "part/description": "Noninverting Buffer / CMOS Logic Level Shifter",
           "part/footprint": "SC-70",
           "part/stock": [{"stock/currency": "usd",
                           "stock/price": 0.1673,
                           "stock/quantity": 200,
                           "stock/storage-id": "1pbr3bmcfg4f59azmvsyftqsxq",
                           "stock/timestamp": 1400928853000},
                          {"stock/quantity": -2,
                           "stock/storage-id": "1pbr3bmcfg4f59azmvsyftqsxq",
                           "stock/timestamp": 1421068653000},
                          {"stock/comments": "LED Bracelet 2.0",
                           "stock/quantity": -1,
                           "stock/storage-id": "1pbr3bmcfg4f59azmvsyftqsxq",
                           "stock/timestamp": 1451661746344}],
           "part/owner": "411k7fb41agesa0tgcbcjbc46q",
           "part/linked-id": "f3ar9ej8npk059dnmfmh6xvcw6",
           "part/name": "M74VHC1GT126DF1G",
           "part/type": "linked",
           "part/manufacturer": "onsemi",
           "part/mpn": "M74VHC1GT126DF1G",
           "part/created": 1400928853000},
  "partsbox.status/category": "ok",
  "partsbox.status/message": "OK"
}

General design and notes

This is not a REST API. REST was designed for representing resources and manipulating them directly through create, read, update and delete operations. PartsBox is much more about performing complex operations and getting aggregated information. While there is a database underneath, not all objects can be directly manipulated, and there are many consistency checks and constraints to be enforced. Therefore, the API is operation-oriented. It is possible to get all the data objects, but it isn't always possible to directly change them directly.

Modes

The API can use one of two serialization methods: either JSON or EDN. The default is JSON, but if you prefer EDN, pass an additional "mode" parameter set to "edn" to any operation, which will cause PartsBox to use EDN for parsing parameters and generating return values.

Passing parameters

Parameters can be passed in several ways, with each subsequent method overriding the previous ones:

• Form URL-encoded
• Multipart
• JSON body
• Query

The recommended way is to use POST requests with a text body (JSON or EDN) containing the object with parameters. It is possible to override some parameters using query strings, or use GET requests with query strings for simpler API calls where only string parameters are required. Note that query strings in GET requests do not allow passing anything else than a string, so certain calls will never work. For example, it isn't possible to pass an integer stock/quantity in a query string.

Some API parameters described in the documentation will be available only with certain plan features.

Return values

Every API call returns a JSON or EDN object with status information. Additionally, when data is being returned, it will be available under the key data. The only exception to this are methods that return images (for example, the image of an ID Anything™ QR code), in which case an image with an appropriate Content-Type will be returned.

Errors

Errors will result in HTTP error codes, with responses also containing a JSON object with status information.

Date and time handling

PartsBox stores all date/time information using 64-bit UNIX timestamps in UTC time zone.

WARNING: It is your responsibility to convert to and from your time zone. This will not be done for you automatically (as done when accessing PartsBox in a browser), and can easily be a source of errors.

Areas most likely to change

• Projects: planned introduction of project versioning might mean changes in the way project entries are retrieved.
• Stock entries: work on features like stock allocations, reservations, planned builds is already in progress. This means that stock entries will start having a status and will not necessarily represent the stock that is on-hand and available. There will be additional API calls for calculating the currently available stock, as it is not an obvious operation.

Authentication

Calls to the API require authentication. PartsBox supports authentication using an API key, or using Oauth2 (support coming soon).

API keys can be generated in the Settings | Data panel. The Hobbyist/Maker plan allows one API key, for accessing your personal database.

Commercial users can add multiple API users with different roles. API users do not count towards the organization user limit, so you can create as many as you need. Choose a meaningful name for an API user, as it will be shown in places like stock and build history. If your plan includes Role-Based Access Control (RBAC), you can also define your own roles with specific permissions (in the Sharing tab), limiting the access for each API user individually.

Please guard your API keys carefully, as they provide full access to your PartsBox database. Make sure not to keep them in your code repositories.

Every call to the API must have an Authorization header containing the API key. Example: Authorization: APIKey partsboxapi_fg29zq83d8gfbcbxkdsexfdw950b98a70be5fd20da6b72dc8ed3b2c11f756fba

Endpoints

All HTTP API requests are of the form https://api.partsbox.com/api/1/[operation]. Please do not use other hosts than api.partsbox.com — even if it works today, it is not guaranteed in the future.

For example, to get information about a part, you would make a GET or POST request to https://api.partsbox.com/api/1/part/get.

Support, reporting bugs and problems, feature requests

The API is in its early days and it is very much subject to change. Please do not assume that it is a contract. Things will be renamed and reshuffled. If you are looking for long-term stability, please wait until a long-term supported (LTS) API version is announced.

The API is available for every PartsBox user, including those on the free Hobbyist/Maker plan. However, please understand that it is impossible to provide support and help for everyone without ruining the business. This is why support for the API is different than anywhere else in PartsBox. Specifically:

• If you are on a commercial plan, you can expect normal support, with the caveat of the API still being in its early days and being subject to change.
• If you have a free Hobbyist/Maker account, please do not expect a reply to your E-mails about the API. Your E-mail will always be read, and bug reports, observations, feature requests (especially with descriptions of real-world scenarios) are very welcome — but do not expect that you will get a response. Communication has to be one-way in order for the business to be viable in the long term.

Rate limiting

Please expect rate limits to be enforced, to be announced later. If you are interfacing to the PartsBox API, plan ahead and implement rate limiting right from the start.

Warnings and pitfalls

The API does a lot of checking, but it will not always prevent you from shooting yourself in the foot. Be extra careful with destructive operations: deleting parts or reverting builds are especially dangerous, as you might not realize what else in PartsBox depends on the part's stock history being there.

Modifying stock history is similarly problematic: if you modify the quantity in an older add stock entry or delete the entry altogether, subsequent remove stock entries will remain, and you might end up with negative stock counts. PartsBox tries very hard to prevent that from happening, but not every possible problem can be detected.

PartsBox has no knowledge of time zones. Timestamps are 64-bit numbers representing the UNIX time in UTC. If you just convert your local time to a timestamp, it will not be UTC, and you will get incorrect times shown in the web interface. To store timestamps, you must convert your date and time to UTC, and then convert it to a 64-bit timestamp.

PartsBox does not store the total stock count anywhere. In order to get stock counts, you need to go through stock history and calculate them. However, please do not assume that you can simply use the sum of quantity fields. After stock statuses are introduced, this will conflate stock that is on-hand with stock that has been ordered, allocated or reserved. You will need to compute totals for each status separately.

Terms of Service

All of the PartsBox Terms of Service apply.

PartsBox reserves the right to terminate your API access at any time, for any reason.

Please note that PartsBox® is a registered trademark. If you intend to publish your code, make sure that the name of the project does not include "PartsBox".

The API is intended for interfacing your software with PartsBox in order to allow automation. You are specifically not allowed to create new user interfaces (apps, shells) that provide a significant part of the functionality of the PartsBox user interface. In other words, automating is fine, building a new inventory control app that uses the API as an engine is not.

This will return data for a single part. If this is a linked part, there will be a part/linked-id field, but you will not get all linked information (such as specs or datasheet links), because of licensing restrictions. part/mpn and part/manufacturer fields will be overriden based on linked data. :part/description will contain either the linked description, or a local one if it has been edited.

This can only be used to create local parts or meta-parts (e.g. you can't create a sub-assembly part directly). To create a linked part, you will need to create a local part first then use the UI to link it manually.

This is a dangerous operation, as it affects build histories, past orders and your stock history. Do not delete parts that are used in projects.

Returns a list of sources for a part. If multiple lots exist for a part, they will be aggregated so that the total stock for this part in each storage location is returned.

This answers the question: "where is this part stored?" by looking at the stock history and returning sources, aggregating lots so that every storage location for a part appears only once.

Returns a list of sources for a part, including every lot as a separate source.

This will produce a list of all lots for stock of this part, with their current quantities.

Returns the total stock count for the specified part. If optional storage/id is supplied, will only return the stock count for inventory in that storage location.

Stock history for parts is stored as a list of timestamped stock entries. Every stock entry has a quantity and a timestamp, but pricing information is optional.

Warning: work on features like stock allocations, reservations and planned builds is already in progress. This means that in the near future stock entries will have a stock/status field and will not always represent the stock that is on-hand and available.

PartsBox does not store the total stock count anywhere. In order to get stock counts, you need to go through stock history and calculate them, or use the provided API functions. However, please do not assume that you can simply use the sum of stock/quantity fields. After stock statuses are introduced, this will conflate stock that is on-hand with stock that has been ordered, allocated or reserved. You will need to compute totals for each status separately.

It is recommended to use the provided API functions for calculating/summarizing stock.

If you pass in lot data, it will be used when creating the new lot for added stock. Note that some parameters might not be available, depending on the features in your plan.

If you pass in order data, an order will be created. You can also link this stock to an existing order by passing stock/order-id. For stock that is linked to orders, stock/vendor-sku is mandatory.

If you add a price, then currency becomes mandatory as well.

Stock sources are identified by part id, storage id, and (in plans with lot control) lot id. Quantity is a positive integer: the number of parts to remove.

If split-lot? is true, allows for lot splitting, and information for the newly created lot can be provided. The new lot will keep a reference to the previous lot, so that tracking is possible. The newly created lot id will be returned in the response.

Stock entries are identified by stock/part-id and stock/timestamp, so these fields are mandatory. Note that updating stock/quantity in historical stock entries is dangerous and can lead to permanent database breakage — if you have an add-stock entry for 100pcs, and later remove 100pcs, modifying the quantity in the add-stock entry to 50pcs will result in negative stock. PartsBox does its best to prevent you from shooting yourself in the foot, but it cannot detect every possible problem. It is highly recommended to only modify stock/quantity in the latest entry in a stock history for a part.

Lot support in the API is a work in progress.

This will return data for a single lot identified by a lot id.

Only description and tags can be updated, see also storage/rename and storage/change-settings.

Renaming a storage location might fail if there is already another location with the same target name.

Given a list of storage location ids, will attempt to set the parameter supplied as param to the boolean value.

There are three possible parameters. Single-part: This location will only accept one part and will not appear when adding stock for other parts than the one already stored. Useful for nuts, bolts, washers, or small drawers containing only a single type of component. Existing parts only: this location will only accept stock for parts which are already stored there, and will not appear when adding stock for other parts. Full: this location will not accept any new stock and will never appear when adding stock.

Archiving a storage location makes it not show up in normal usage. History for parts that used to be stored in this location will show the location name and you will be able to access this archived location through direct links or by going to the archived location list. You will also be able to un-archive (restore) the location. Do this for storage locations that you will not use anymore, but would like to remember.

This storage location will be restored (un-archived) and will behave like a normal storage location again.

Calculates the stock of parts in a given storage location and returns a list of part sources. If multiple lots exist for a part, they will be aggregated so that the total per-part stock is returned.

Calculates the stock of parts in a given storage location and returns a list of part sources. If multiple lots exist for a part, they will all be returned, each as an individual source.

Returns either project entries (the current version of the project), or if build/id is also supplied, build entries for that particular build.

Archiving a project causes it not to show up in normal usage. It still exists in the database and can be accessed directly by id. It is also possible to un-archive (restore) the project. This is useful for projects that are no longer actively used, but should be kept in the database to maintain history and traceability.

This project will be restored (un-archived) and will behave like a normal project again.

Order support in the API is a work in progress.

This will return data for a single order identified by an order id.

Returns a list of order entries, which are actually stock entries for parts in the order.

Receives order entries into the specified storage location. Only orders with the status 'ordered' can be received. If optional stock-entries is provided, receives only the specified order entries, otherwise receives all order entries that haven't been received yet. With lot control, information for the newly created lot can be provided optionally using the optional lot parameter. lot/name will only be used if a single lot is being created (e.g. a single order entry is being received). Once all order entries have been received, the status of the order will be automatically switched from 'ordered' to 'received'.

Offer support in the API is a work in progress. Please expect them to be accessible in future versions of the API.

Purchase list support in the API is a work in progress. Please expect them to be accessible in future versions of the API.

This is a public API endpoint that does not require authentication. It returns a PNG image directly (the response has a Content-Type: image/png) and is designed to easily convert ids into QR codes containing an ID Anything™ URL.

Command-line example:

curl 'https://api.partsbox.com/api/1/id-anything-qr?id=6n1n9dhjsagyw92ebhewhxgs7d' -o qr-code.png