API

This is an overview of the main points to keep in mind when using the Pakk API (Version 2). For details of all available endpoints and their input and output schema, refer to the autogenerated documentation for each Pakk entity.

Integrations

• Before you can authenticate to the API, you'll need to create an Integration in your Pakk account. Go to Account Settings > Integrations and add a new Integration to the Integeration Registry

• Integrations are meant to be wrappers for API projects, so name each integration appropriately, e.g., "orders-to-warehouse" or "price-updater"

• Once you have an integration set up, you can generate one or more API Keys for that integration

• Deleting an integration will delete the integration, all its API keys (see below) and all of the Key-Value data it may have written to the database (see below)

• If you need to temporarily disable an integration (rather than permanently deleting it), uncheck Enabled next to the integration you wish to disable

• If you need to stop an integration writing to the 'key-value store', you can uncheck Allow Write Data

API Keys

• API Keys live inside an Integration which needs to exist before keys can be generated

• You can generate multiple keys for each integration

• Use different keys to separate access to the integration for each person/machine that needs it

• If you need to revoke access to the API, you can do so on a key-by-key basis by simply deleting the key in question

• For security, the key itself is only visible immediately after generation. Copy the key to where it is going to be used immediately before navigating away as you will never be able to see it again

• If you generate a key but forget to copy it for use, just delete it and generate a new one

Authentication

• To access the API, the key needs to be included as the Authorization header with all API calls

• There is no need to include the word Bearer in the header value

• Do not tamper with the key in any way - if you do, it will not pass authentication

• Note that API access is at 'account owner' permission level, so never allow a key to become exposed - it would allow complete access to your Pakk account

API Structure

• The Pakk API can be thought of as following a 'generic' architecture. There is a set of 4 endpoints for most entities: get a list, get a single record, create a new record, update an existing record

• A few entities do not allow writes, so have only 2 endpoints

• For requesting a list, you must send a filter - the shape of the filter request is the same regardless of which entity you are requesting

• Lists can return a maximum of 1000 records

• The fields available on both requests and responses are essentially the full set of fields exposed by that entity. As well as in this documentation, you can get full details of each field, along with more in-depth help by turning on Show API Field Paths in your account and clicking on each field name on each entity screen to view its 'in-field help'

• When creating new records, each entity has its own set of required fields - again, use the admin panel to establish which fields are required and which are optional

• When updating (patching) records, only the fields sent in the request will be updated - all others will be left untouched. Note that for fields that are lists or maps (dictionaries), you need to send the whole field when editing or updating the list/map, otherwise existing members will be lost (doesn't apply to writing to the Key-Value store - see below)

Integration Data (Key-Value Store)

• Integrations have access to a namespaced key-value store to which proprietary data can be written on any record of any entity

• This field is always called integrationsData.{{integrationName}} where {{integrationsName}} is the name of the integration as set up in Account Settings

• An integration can only write to its own namespace - any attempts to write to any other namespace will fail

• You do not have to send the entire contents of the KV store for that integration when patching integrationsData.{{integrationName}}. For example, if you want to set the value of key1 to val1, you only need to send integrationsData.{{integrationName}}.key1: val1 - none of the other keys in the namespace will be affected

• The key-value store is intended for writing identifiers, flags and other small pieces of data - it is not meant to be used as a fully-fledged database

• An integration can write up to 20 keys per record

• Maximum key size is 64 bytes

• Maximum value size is 1024 bytes