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.

Parts

part/get
Get single part data

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.

Parameters

    part/id (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single part

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/all

Parameters
None
Return value

(map):

Map contents:
  • data: Data for all parts

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/create
Create a new part

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.

Parameters

    part/type (enum): Part type

    Possible values:
    "sub-assembly", "meta", "linked", "local"

    part/name (string): Part name (or local/internal part name if part is linked)

    [optional] part/description (string): Part description. In linked parts, this will be filled from linked data, unless edited locally.

    [optional] part/notes (string): This field stores your notes/comments regarding the part. Markdown syntax is supported and links will be automatically highlighted.

    [optional] part/footprint (string):

    [optional] part/tags (array): A list of tags

    Array element:

    (string): Tag

    [optional] part/attrition (map): Part attrition parameters

    Map contents:
    • percentage (number): Percentage of parts wasted

    • quantity (integer): Minimum number of parts wasted

    [optional] part/low-stock (map): Low stock levels

    Map contents:
    • report (integer): Include in low-stock report if quantity on hand is lower than this

Return value

(map):

Map contents:
  • data (map): Contains the newly created part id

    Map contents:
    • part/id (string): Part id / UUID in 26-character compact form

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/update
Update data for a part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    [optional] part/name (string): Part name (or local/internal part name if part is linked)

    [optional] part/description (string): Part description. In linked parts, this will be filled from linked data, unless edited locally.

    [optional] part/notes (string): This field stores your notes/comments regarding the part. Markdown syntax is supported and links will be automatically highlighted.

    [optional] part/footprint (string):

    [optional] part/tags (array): A list of tags

    Array element:

    (string): Tag

    [optional] part/attrition (map): Part attrition parameters

    Map contents:
    • percentage (number): Percentage of parts wasted

    • quantity (integer): Minimum number of parts wasted

    [optional] part/low-stock (map): Low stock levels

    Map contents:
    • report (integer): Include in low-stock report if quantity on hand is lower than this

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/delete
Delete a part

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.

Parameters

    part/id (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/add-meta-part-ids
Add member parts (equivalent substitutes) to a meta-part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    part/part-ids (array): A list of part ids

    Array element:

    (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/remove-meta-part-ids
Remove member parts from a meta-part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    part/part-ids (array): A list of part ids

    Array element:

    (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/add-substitute-ids
Add substitutes to a part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    part/substitute-ids (array): A list of part ids

    Array element:

    (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/remove-substitute-ids
Remove substitutes from a part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    part/part-substitute-ids:

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/update-custom-fields
Update (possibly creating) custom fields for a part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    custom-fields (array): A list of custom fields to create or update

    Array element:

    (map): Custom field, consisting of a key and value

    Map contents:
    • key (string): Custom field key, limited to 256 characters

    • value (string): Custom field value, limited to 1024 characters

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/delete-custom-field
Delete a custom field from a part

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    custom-field-key (string): Custom field key, limited to 256 characters

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/storage
Return a list of sources for a part (aggregating lots)

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.

Parameters

    part/id (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of part sources

    Array element:

    (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/lots
Return a list of sources for a part

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.

Parameters

    part/id (string): Part id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of part sources

    Array element:

    (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

part/stock
Return the total stock count for a part

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.

Parameters

    part/id (string): Part id / UUID in 26-character compact form

    [optional] storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • source/quantity (integer): Stock quantity

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Stock

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.

stock/add
Add stock for a part.

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.

Parameters

    stock/part-id (string): Part id / UUID in 26-character compact form

    stock/storage-id (string): Storage location id / UUID in 26-character compact form

    stock/quantity (integer): Stock quantity

    stock/comments (string): Comments for this stock entry

    [optional] stock/price (number): Price per unit

    [optional] stock/currency (enum):

    Possible values:
    "bgn", "pln", "aud", "krw", "chf", "cad", "sek", "rub", "zar", "usd", "nok", "brl", "uah", "aed", "cny", "jpy", "huf", "hkd", "nzd", "inr", "czk", "idr", "ils", "mxn", "sgd", "ron", "myr", "php", "gbp", "hrk", "try", "twd", "eur", "dkk", "thb"

    [optional] stock/order-id (string): Order that this stock entry belongs to / Order id / UUID in 26-character compact form

    [optional] stock/vendor-sku (string): For stock ordered from a distributor, the vendor SKU that was ordered

    [optional] order (map): Information about the newly created order

    Map contents:
    • order/created (64-bit UNIX timestamp (UTC)): The date when this order was created

    • order/vendor-name (string): The name of the vendor/distributor

    • order/number (string): Vendor/distributor order number (as assigned by the vendor)

    • order/invoice-number (string): Vendor/distributor invoice number

    • order/po-number (string): Your purchase order number. Leave blank to use the auto-generated ID.

    • order/comments (string): Your comments for this order

    • order/notes (string): Any additional notes stored with the order. Markdown syntax is supported and links will be automatically highlighted.

    • order/tags (array): A list of tags

      Array element:

      (string): Tag

    • order/arriving (64-bit UNIX timestamp (UTC)): Expected delivery date for the entire order. Indicative only: order entries have their own expected delivery dates.

    [optional] lot (map): Information about the newly created lot

    Map contents:
    • lot/created (64-bit UNIX timestamp (UTC)): The date when this lot was created.

    • lot/name (string): Lot name or number as defined within the company. A lot represents a specific batch of parts and can have data associated with it. Assigning a lot name is not mandatory: PartsBox automatically generates unique IDs for every lot.

    • lot/description (string): A short optional description of the lot.

    • lot/comments (string): Any other comments that will be stored with this lot.

    • lot/expiration-date (64-bit UNIX timestamp (UTC)): Date when this lot expires

    • lot/tags (array): A list of tags

      Array element:

      (string): Tag

    • lot/order-id (string): Order id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

stock/remove
Remove stock from a specified source

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.

Parameters

    stock/source (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

    stock/quantity (integer): Stock quantity

    [optional] stock/comments (string): Comments for this stock entry

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

stock/move
Move stock to a different storage location

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.

Parameters

    stock/source (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

    stock/quantity (integer): Stock quantity

    stock/comments (string): Comments for this stock entry

    stock/storage-id (string): Storage location id / UUID in 26-character compact form

    [optional] split-lot? (boolean):

    [optional] lot (map): Information about the newly created lot

    Map contents:
    • lot/created (64-bit UNIX timestamp (UTC)): The date when this lot was created.

    • lot/name (string): Lot name or number as defined within the company. A lot represents a specific batch of parts and can have data associated with it. Assigning a lot name is not mandatory: PartsBox automatically generates unique IDs for every lot.

    • lot/description (string): A short optional description of the lot.

    • lot/comments (string): Any other comments that will be stored with this lot.

    • lot/tags (array): A list of tags

      Array element:

      (string): Tag

    • lot/expiration-date (64-bit UNIX timestamp (UTC)): Date when this lot expires

Return value

(map):

Map contents:
  • lot/id (string): Lot id / UUID in 26-character compact form

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

stock/update
Update a stock entry

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.

Parameters

    stock/part-id (string): Part id / UUID in 26-character compact form

    stock/timestamp (64-bit UNIX timestamp (UTC)): Timestamp when stock entry was created

    [optional] stock/comments (string): Comments for this stock entry

    [optional] stock/quantity (integer): Stock quantity

    [optional] stock/price (number): Price per unit

    [optional] stock/currency (enum):

    Possible values:
    "bgn", "pln", "aud", "krw", "chf", "cad", "sek", "rub", "zar", "usd", "nok", "brl", "uah", "aed", "cny", "jpy", "huf", "hkd", "nzd", "inr", "czk", "idr", "ils", "mxn", "sgd", "ron", "myr", "php", "gbp", "hrk", "try", "twd", "eur", "dkk", "thb"

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Lots

Lot support in the API is a work in progress.

lot/get
Get single lot data

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

Parameters

    lot/id (string): Lot id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single lot

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

lot/update
Update single lot data

Parameters

    lot/id (string): Lot id / UUID in 26-character compact form

    [optional] lot/created (64-bit UNIX timestamp (UTC)): The date when this lot was created.

    [optional] lot/name (string): Lot name or number as defined within the company. A lot represents a specific batch of parts and can have data associated with it. Assigning a lot name is not mandatory: PartsBox automatically generates unique IDs for every lot.

    [optional] lot/description (string): A short optional description of the lot.

    [optional] lot/comments (string): Any other comments that will be stored with this lot.

    [optional] lot/expiration-date (64-bit UNIX timestamp (UTC)): Date when this lot expires

    [optional] lot/tags (array): A list of tags

    Array element:

    (string): Tag

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

lot/all

Parameters
None
Return value

(map):

Map contents:
  • data: Data for all lots

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Storage

storage/get
Get data for a single storage location

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single storage location

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/all
Get data for all storage locations

Parameters
None
Return value

(map):

Map contents:
  • data: A list with data for all storage locations

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/update
Update data for a storage location

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

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

    [optional] storage/description (string): Storage location description

    [optional] storage/tags (array): A list of tags

    Array element:

    (string): Tag

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/rename
Change the name of a storage location

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

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

    storage/name (string): Storage location name

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/change-settings
Change settings for a storage location

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.

Parameters

    ids (array): A list of storage location ids that should have settings changed

    Array element:

    (string): Storage location id / UUID in 26-character compact form

    param (enum): Parameter (setting) for a storage location

    Possible values:
    "full?", "single-part?", "existing-parts-only?"

    value (boolean):

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/archive
Archive a storage location

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.

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/restore
Restore an archived storage location

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

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/parts
Return a list of part sources in a storage location (aggregating lots)

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.

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of part sources

    Array element:

    (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

storage/lots
Return a list of part sources in a storage location (lots not aggregated)

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.

Parameters

    storage/id (string): Storage location id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of part sources

    Array element:

    (map): A source of parts. Can be used to specify where stock is to be taken from (using `source/part-id`, `source/storage-id` and `source/lot-id`), or to summarize available stock.

    Map contents:
    • source/part-id (string): Part id / UUID in 26-character compact form

    • source/storage-id (string): Storage location id / UUID in 26-character compact form

    • source/lot-id (string): Lot id / UUID in 26-character compact form

    • source/quantity (integer): Stock quantity

    • source/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • source/first-timestamp (64-bit UNIX timestamp (UTC)): First (oldest) timestamp of stock entries summarized by this source

    • source/last-timestamp (64-bit UNIX timestamp (UTC)): Last (most recent) timestamp of stock entries summarized by this source

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Projects

project/get
Get data for a single project

Parameters

    project/id (string): Project id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single project

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/all
Get data for all projects

Parameters
None
Return value

(map):

Map contents:
  • data: A list with data for all projects

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/create
Create a new project, optionally also adding entries

Parameters

    project/name (string): Project name

    [optional] project/description (string): Project description

    [optional] project/notes (string): Longer-form project notes (can use Markdown)

    [optional] entries (array):

    Array element:

    (map): An entry in a project/BOM

    Map contents:
    • entry/part-id (string): Part id / UUID in 26-character compact form

    • entry/quantity (integer): Quantity for this project/BOM entry

    • entry/name (string): A BOM name for this entry

    • entry/comments (string): Additional comments

    • entry/designators (array): Set of designators

      Array element:

      (string): Designator

    • entry/order (integer): Ordering within the BOM (future extension: entries will be sorted by this number)

    • entry/cad-footprint (string): Footprint from CAD program (currently unused)

Return value

(map):

Map contents:
  • project/id: ID of the newly created project

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/update
Update project data

Parameters

    project/id (string): Project id / UUID in 26-character compact form

    [optional] project/name (string): Project name

    [optional] project/description (string): Project description

    [optional] project/notes (string): Longer-form project notes (can use Markdown)

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/delete
Delete a project

Parameters

    project/id (string): Project id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/get-entries
Get project entries, or entries for a specific project build

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

Parameters

    project/id (string): Project id / UUID in 26-character compact form

    build/id (string): Build id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of entries

    Array element:

    (map): An entry in a project/BOM

    Map contents:
    • entry/id (string): Entry id / UUID in 26-character compact form

    • entry/part-id (string): Part id / UUID in 26-character compact form

    • entry/quantity (integer): Quantity for this project/BOM entry

    • entry/name (string): A BOM name for this entry

    • entry/comments (string): Additional comments

    • entry/designators (array): Set of designators

      Array element:

      (string): Designator

    • entry/order (integer): Ordering within the BOM (future extension: entries will be sorted by this number)

    • entry/cad-footprint (string): Footprint from CAD program (currently unused)

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/add-entries
Add entries to a project/BOM

Parameters

    project/id (string): Project id / UUID in 26-character compact form

    entries (array):

    Array element:

    (map): An entry in a project/BOM

    Map contents:
    • entry/part-id (string): Part id / UUID in 26-character compact form

    • entry/quantity (integer): Quantity for this project/BOM entry

    • entry/name (string): A BOM name for this entry

    • entry/comments (string): Additional comments

    • entry/designators (array): Set of designators

      Array element:

      (string): Designator

    • entry/order (integer): Ordering within the BOM (future extension: entries will be sorted by this number)

    • entry/cad-footprint (string): Footprint from CAD program (currently unused)

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/update-entries
Update (modify) entries in a project/BOM

Parameters

    project/id (string): Project id / UUID in 26-character compact form

    entries (array):

    Array element:

    (map): An entry in a project/BOM

    Map contents:
    • entry/id (string): Entry id / UUID in 26-character compact form

    • entry/part-id (string): Part id / UUID in 26-character compact form

    • entry/quantity (integer): Quantity for this project/BOM entry

    • entry/name (string): A BOM name for this entry

    • entry/comments (string): Additional comments

    • entry/designators (array): Set of designators

      Array element:

      (string): Designator

    • entry/order (integer): Ordering within the BOM (future extension: entries will be sorted by this number)

    • entry/cad-footprint (string): Footprint from CAD program (currently unused)

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/delete-entries
Delete entries in a project/BOM

Parameters

    project/id (string): Project id / UUID in 26-character compact form

    ids (array): A list of entry ids to delete

    Array element:

    (string): Entry id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

project/get-builds
Get all builds for a project/BOM

Parameters

    project/id (string): Project id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: A list of builds

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

build/get
Get a single project build identified by `build/id`

Parameters

    build/id (string): Build id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single build

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

build/update
Update (modify) a project build

Parameters

    build/id (string): Build id / UUID in 26-character compact form

    build/comments (string): Comments for this build

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Orders

Order support in the API is a work in progress.

order/get
Get single order data

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

Parameters

    order/id (string): Order id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data: Data for a single order

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

order/all

Parameters
None
Return value

(map):

Map contents:
  • data: Data for all orders

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

order/get-entries
Get stock entries in an order

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

Parameters

    order/id (string): Order id / UUID in 26-character compact form

Return value

(map):

Map contents:
  • data (array): A list of stock entries

    Array element:

    (map): A stock entry, which might represent stock that is on hand, order entries, or planned stock that will become available in the future.

    Map contents:
    • stock/id (string): Stock entry id / UUID in 26-character compact form

    • stock/part-id (string): Part id / UUID in 26-character compact form

    • stock/storage-id (string): Storage location id / UUID in 26-character compact form

    • stock/lot-id (string): Lot id / UUID in 26-character compact form

    • stock/quantity (integer): Stock quantity

    • stock/price (number): Price per unit

    • stock/currency (enum):

      Possible values:
      "bgn", "pln", "aud", "krw", "chf", "cad", "sek", "rub", "zar", "usd", "nok", "brl", "uah", "aed", "cny", "jpy", "huf", "hkd", "nzd", "inr", "czk", "idr", "ils", "mxn", "sgd", "ron", "myr", "php", "gbp", "hrk", "try", "twd", "eur", "dkk", "thb"

    • stock/timestamp (64-bit UNIX timestamp (UTC)): Timestamp when stock entry was created

    • stock/status (enum): Stock status, no status means on-hand stock.

      Possible values:
      "ordered", "reserved", "allocated", "in-production", "in-transit", "planned", "rejected", "being-ordered"

    • stock/comments (string): Comments for this stock entry

    • stock/order-id (string): Order that this stock entry belongs to / Order id / UUID in 26-character compact form

    • stock/vendor-sku (string): For stock ordered from a distributor, the vendor SKU that was ordered

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

order/receive
Receive order entries into inventory

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'.

Parameters

    order/id (string): Order id / UUID in 26-character compact form

    storage/id (string): Storage location id / UUID in 26-character compact form

    [optional] stock-entries (array):

    Array element:

    (map): A stock entry specifying stock being received from an order. Must contain an identifier: `stock/id` must be specified, so that a stock entry can be uniquely identified. May also optionally specify the received quantity, which must be less than or equal the quantity for that stock entry in the order.

    Map contents:
    • stock/id (string): Stock entry id / UUID in 26-character compact form

    • stock/quantity (integer): Stock quantity

    [optional] stock/comments (string): Comments for this stock entry

    [optional] lot (map): Information about the newly created lot

    Map contents:
    • lot/created (64-bit UNIX timestamp (UTC)): The date when this lot was created.

    • lot/name (string): Lot name or number as defined within the company. A lot represents a specific batch of parts and can have data associated with it. Assigning a lot name is not mandatory: PartsBox automatically generates unique IDs for every lot.

    • lot/description (string): A short optional description of the lot.

    • lot/comments (string): Any other comments that will be stored with this lot.

    • lot/tags (array): A list of tags

      Array element:

      (string): Tag

    • lot/expiration-date (64-bit UNIX timestamp (UTC)): Date when this lot expires

Return value

(map):

Map contents:
  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Offers

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

Purchase Lists

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

ID Anything™

id-anything-qr
Return a PNG image with a QR code of the supplied ID Anything™ id

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
Parameters

    id (string): UUID in 26-character compact form

Return value

image/png:

Global

db/download-all-data

Parameters
None
Return value

(map):

Map contents:
  • data: All of your PartsBox data

  • partsbox.status/category (string): Category of the status or problem encountered, `status/ok` if everything is OK

  • partsbox.status/message (string): Status message with an additional description

Control your inventory, ordering and production

Try the demo

Plans & pricing