KanbanBOX REST API

KanbanBOX REST API is an easy interface to access KanbanBOX main resources.

URL

You can access the KanbanBOX REST API in the production environment at:

https://api.kanbanbox.com

The URL is in the following format:

protocol://api.kanbanbox.com/api_name/version/resource.format?parameters

Where:

Field	Description	Accepted values
Protocol	The communication protocol	https
API name		rest
Version	The KanbanBOX REST API version you want to use, written as a “v” followed by the version number	v0 v1
Resource	The KanbanBOX resource which you want to access.	loops cards parts …
Format	The desired response format. Default format is json	xml json csv
Parameters		firstparameter=firstvalue&secondparameter=secondvalue

You can access the KanbanBOX REST API in the test environment at:

https://apitest.kanbanbox.com

METHODS

KanbanBOX REST API accepts the following standard HTTP methods:

Method	Usage
GET	Get information about existent resources.
POST	Create new resources.
PUT	Update the information of a specific resource.
DELETE	Delete specific resources.

Not every resource will accept every method. Please refer to the specific resource description to know which methods you can use with it.

The HTTP method should be specified in the HTTP request headers. If you have problems creating a request in any specific method, you can create the request using GET or POST method (the most standard ones) and can add the real method name in the request parameters:

_method=methodname

RESPONSES

KanbanBOX REST API will use standard HTTP status codes in each response.

These are the currently used status codes:

HTTP Status Code	Meaning
200	OK
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
500	Internal Server Error

You may want to always receive a 200 status code. In this case, you must add the suppress_response_code parameter to the request:

suppress_response_code=true

that will set the status code to 200 and will add the original status code to the responseCode field inside the metadata.

Should an error occur, the response will have at least one of this information:

Value	Meaning
message	Message for the final user.
error_number	Error number.
error_message	Message for the developer.

AUTHORIZATION AND AUTHENTICATION

Authorization/authentication can be done in two different ways:

• adding the Authorization Bearer parameter to the HTTP request header:

Authorization=Bearer api_key_40_characters_long  

• adding the X-API-KEY parameter to the HTTP request header:

X-API-KEY=api_key_40_characters_long  

Every KanbanBOX user can have his API key. The user API key, when set, is visible in the user settings page.

In case of a user present in a Group license, with the API Key has to be specified the plant license to access, adding the Kanbanbox-Organization-External-Id parameter to the HTTP request header.

Kanbanbox-Organization-External-Id={plant_ID}

Error response examples

Wrong Authorization Bearer token: HTTP Status Code: 401

{
  "status": false,
  "metadata": {
    "message": "The provided Bearer token '{api_key}' is not valid"
  }
}

Wrong X-API-KEY: HTTP Status Code: 401

{
  "status": false,
  "metadata": {
    "message": "The provided API Key '{api_key}' is not valid"
  }
}

Unauthorized API: HTTP Status Code: 403

{
  "status": false,
  "error": "Warning! You do not have the required permissions!"
}

cURL usage example

Using the Authorization Bearer token:

curl -H "Authorization: Bearer FBg5eR35AwqgRT53F2VgfKqUUKuWoZDfJot7AwK" -X PUT -d "new_status=full" https://api.kanbanbox.com/rest/v0/cards/Y7YHWNGM.json  

Using the X-API-KEY parameter:

curl -H "X-API-KEY: FBg5eR35AwqgRT53F2VgfKqUUKuWoZDfJot7AwK" -X PUT -d "new_status=full" https://api.kanbanbox.com/rest/v0/cards/Y7YHWNGM.json  

where:

-H: header parameters  
-X: HTTP method for the request  
-d: request parameters  

All characters of the url must be url-encoded (meaning that, as an example, white spaces must be replaced by %20). As an alternative, data can be added with the --data-urlencode parameter instead of -d, letting cURL to take care of the encoding process. Repeat -d or --data-urlencode one time for each different parameter you want to add to the request.

If the url contains the characters [ ] { }, add the parameter -g in order to prevent cURL from interpreting them unexpectedly.

In case of GET requests, you have to add -G in order to convert the parameters specified in -d or --data-encode in GET parameters.

TESTING KANBANBOX REST API

An easy and free tool to test KanbanBOX REST API is “Postman” app, available here:

https://www.getpostman.com

A few things to remember:

• add the Authorization Bearer token or the X-API-KEY value in the Headers
• for PUT and DELETE requests, don't send the parameters as “form-data”. Send the parameters as “x-www-form-urlencoded” or with json or xml format
• for POST requests that required attached files, send the parameters as “form-data”
• all field names are case sensitive and should be written in lowercase

FILTERING AND SORTING

Filtering

Where available, the “filter[]” parameter allows to define one or more filtering criteria. If the criteria are more than one, they will be connected by a logical AND.

The filter[] parameter syntax is:

filter[]={field_name} {operator} {value}

where:

• {field_name} is the name of the field you want apply the criteria to
• {operator} is one of the available comparison operators
• {value} is the comparison value. If the value is a string, it must be enclosed in single quotation marks.

The currently available comparison operators are:

Comparison	Operator	Example
Equality	eq	filter[]=part_number eq 'ABC'
Not equality	ne	filter[]=type_of_kanban ne 'production'
Greater than	gt	filter[]=kanban_quantity gt 100
Greater than or equal	gte	filter[]=kanban_quantity gte 100
Less than	lt	filter[]=lead_time lt 10
Less than or equal	lte	filter[]=lead_time lte 100
Membership	in (...)	filter[]=type_of_kanban in ('move','purchase')

If you experience problems with composing a request with the “filter[]” syntax, you can also specify a key number for each filter condition; for example, you can write as well:

filter[0]=type_of_kanban ne 'production'&filter[1]=kanban_quantity gt 100

Sorting

Where available, the “sort” parameter allows defining sorting rules. The sort parameter takes in a list of comma-separated fields, each with a possible unary negative to imply descending sort order.

Example:

sort=supplier_name,-part_number  

will sort the result firstly for supplier_name in ascending order (a to z), and secondarily for part_number in descending order (z to a).