API documentation

Please contact us if something is unclear or you need more information. We are ready to help you.

Introduction

Welcome to the optiCutter API documentation. Our API provides programmatic access to optiCutter solver engine, allowing developers to integrate our solver into client's enterprise systems. To use the optiCutter API, you need a customer account. Once you have the account, you can get an API token and begin making calls to the API.

Environments

We provide two different environments for our customers: development and production. Development environment is suitable for developing and debugging API clients. This environment specification is exactly the same as the current production environment. All API calls to development environment are free and all solutions are only fake. They are syntactically correct, but the data obtained do not contain a workable solution. The development environment also includes all required API call validations, so when your API client is able to call our development APIs, your client code is fully compatible with our production APIs as well.
Development:
  • suitable for API client development
  • free of charge
  • returns fake solutions
  • API host name: sandbox.api.opticutter.com
Production:
  • suitable for production usage
  • all API calls are billed - based on subscription package
  • returns real solutions
  • API host name: api.opticutter.com

API structure

Our API is based on JSON data format and only HTTP POST method is supported. We provide 3 endpoints:
  • /linear for access to linear solver
  • /panel for access to panel/sheet solver
  • /status for access to account status information
All API calls must also contain an API version. The current version of the API is 1.0 (/v1/). With the new features, we'll release a new version of the API, but the previous versions will remain intact, so our customers don't have to upgrade their clients to the new version, if they want to stay with the older version.

Here are some examples of what an API destination URL should look like:
  • https://api.opticutter.com/v1/linear production API call version 1 to linear solver endpoint
  • https://sandbox.api.opticutter.com/v1/linear development API call version 1 to linear solver endpoint
  • https://sandbox.api.opticutter.com/v1/status development API call version 1 to account status endpoint
Because optiCutter API supports JSON format only, all API calls must contains "Content-type: application/json" HTTP header.

Authentication

All API calls must contain HTTP header named Authorization which contains bearer authorization token.
curl -H "Content-type: application/json" \
	  -H "Authorization: Bearer <TOKEN>" \
	  -X POST http://sandbox.api.opticutter.com/v1/status

Authorization token is available in API status section in optiCutter online application.

Your first API call

Now, it's time to test if everything is set up correctly. API call below will return your current account status. Please, do not forget to use your current API token, instead of <TOKEN> placeholder.
curl -H "Content-type: application/json" \
	  -H "Authorization: Bearer <TOKEN>" \
	  -X POST http://sandbox.api.opticutter.com/v1/status

You should receive this response:
{
	"message": "OK",
	"remaining": 0
}
Because API call used development environment (sandbox.api.opticutter.com) the JSON response contains "remaining":0 as how many API calls remains for this biling period. If you used production environment (api.opticutter.com), the response would contain the actual number of calls remaining.

Endpoints

Linear

Solves linear cutting plans.

Request

Request object contains array of stocks, array of requirements and a single settings object and it's structure is very similar to the form used in our online application.
Recommendation: Familiarize yourself with the Linear Plan Form first.
Request object description
stocks
array, required
Array of all available stocks. Every child object contains two fields: length and count.
length
string, required
Length of the stock.
count
integer, optional
Number of available stocks. Empty or unspecified means an unlimited number of resources.
priority
string, optional
Flag indicates if stock usage is prefered. Default value is empty (all stocks have equal priority). Allowed value is y.
requirements
array, required
Array of all required parts. Every child object must contain two mandatory fields length, count and can contain one optional field label.
length
string, required
Length of the single required part.
count
integer, required
Number of required parts.
label
string, optional
Label of the required part (for easier identification in response).
settings
object, optional
Can contain fields: kerf, leftTrim, rightTrim.
kerf
string, optional
Width of kerf used for cutting. (Blade thickness)
leftTrim
string, optional
Trim/crop on the left side.
rightTrim
string, optional
Trim/crop on the right side.
layoutImages
string, optional
Flag indicates if layout images in SVG format (base64 encoded) are required in response object. Default value is empty (no images in response). Allowed value is y.
Example request
curl -H "Content-type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-X POST -d '{
    "stocks" : [{
    	"length" : "300",
        "count": 10
    }],
    "requirements" : [{
    	"length" : "100", 
        "count": 4
    },
    {
    	"length" : "40", 
        "count": 3
    }],
    "settings": {
    "kerf": "1"
    }
}' https://api.opticutter.com/v1/linear

Response

Response object contains a single solution object, which contains three inner child elements: totalRequiredStocks field, array of requiredStocks and array of layouts objects. Again, solution object is very similar to linear cutting plan solution from our online application. Take a short look at the linear cutting plan results in online application first to understand it's concept.
Response object description
For the sake of clarity, the table below do not contains solution wrapper object.
totalRequiredStocks
integer, required
Total sum of all required stocks.
requiredStocks
array, required
Array of all required stocks and it's counts. Every child object contains three fields: index, length and count.
index
integer, required
Order index of stock element from request's stocks array.
length
string, required
Length of the relevant stock.
Additional information only.
count
integer, required
Number of required stocks.
layouts
array, required
Array of all cut layouts. Every child object contains four objects: count field, stock object, parts array and waste object.
count
integer, required
Number of repetitions of this layout. ("Repetition" value in online application)
stock
single element, required
Stock element used in this layout.
index
integer, required
Order index of stock element from request's stocks array.
length
string, required
Length of the relevant stock.
Additional information only
parts
array, required
A list of all parts that can be cut in this layout. Every child object contains three mandatory fields index, length, count and one optional field label.
index
integer, required
Order index of required element from request's requirements array.
length
string, required
Length of the single required part.
Additional information only
count
integer, required
The number of parts of the same length that can be cut in this layout.
label
string, optional
Label of the required part from request's requirements array.
Additional information only
waste
single element, required
Information object. Holds info about cut and material waste for this layout.
cut
string, optional
Waste after cutting (including trim cuts if provided).
material
string, required
Material left after cutting.
cuts
single element, required
Information object. Holds info about cut count for this layout.
count
integer, required
The number of cuts in this layout.
Example response
{
	"solution": {
		"totalRequiredStocks": 2,
		"requiredStocks": [
			{
				"index": 0,
				"length": "300",
				"count": 2
			}
		],
		"layouts": [
			{
				"count": 1,
				"stock": {
					"index": 0,
					"length": "300"
				},
				"parts": [
					{
						"index": 0,
						"length": "100",
						"count": 2
					},
					{
						"index": 1,
						"length": "40",
						"count": 2
					}
				],
				"waste": {
					"cut": "4",
					"material": "16"
				},
				"cuts": {
                    "count": 4
                }
			},
			{
				"count": 1,
				"stock": {
					"index": 0,
					"length": "300"
				},
				"parts": [
					{
						"index": 0,
						"length": "100",
						"count": 2
					},
					{
						"index": 1,
						"length": "40",
						"count": 1
					}
				],
				"waste": {
					"cut": "3",
					"material": "57"
				},
				"cuts": {
                    "count": 3
                }
			}
		]
	}
}

Panel

Solves panel/sheet cutting plans.

Request

Request object contains array of stocks, array of requirements and a single settings object and it's structure is very similar to the form used in our online application.
Recommendation: Familiarize yourself with the Sheet Plan Form first.
Request object description
stocks
array, required
Array of all available stocks. Every child object contains three fields: length, width, count and grainDirection.
length
string, required
Length of the stock.
width
string, required
Width of the stock.
count
integer, optional
Number of available stocks. Empty or unspecified means an unlimited number of resources.
grainDirection
char, optional
Stock's grain direction. Empty or unspecified means grain direction is not considered for corresponding stock.
Allowed values are h for horizontal grain direction and v for vertical grain direction.

Hint

Horizontal grain direction is parallel with stock's edge entered as length.
Vertical grain direction is parallel with stock's edge entered as width.
priority
string, optional
Flag indicates if stock usage is prefered. Default value is empty (all stocks have equal priority). Allowed value is y.
requirements
array, required
Array of all required panels. Every child object contains four mandatory fields length, width, count, grainDirection and can contain one optional field label.
length
string, required
Length of the single required panel.
width
string, required
Width of the single required panel.
count
integer, required
Number of required panels.
grainDirection
char, optional
Required panel's grain direction. Empty or unspecified means grain direction is not considered for corresponding panel.
Allowed values are h for horizontal grain direction and v for vertical grain direction.

Hint

Horizontal grain direction is parallel with stock's edge entered as length.
Vertical grain direction is parallel with stock's edge entered as width.
label
string, optional
Label of the required panel (for easier identification in response).
settings
object, optional
Can contain fields: kerf, leftTrim, rightTrim, topTrim and bottomTrim.
kerf
string, optional
Width of kerf used for cutting. (Blade thickness)
leftTrim
string, optional
Trim/crop on the left side.
rightTrim
string, optional
Trim/crop on the right side.
topTrim
string, optional
Trim/crop on the top side.
bottomTrim
string, optional
Trim/crop on the bottom side.
layoutImages
string, optional
Flag indicates if layout images in SVG format (base64 encoded) are required in response object. Default value is empty (no images in response). Allowed value is y.
Example request
curl -H "Content-type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-X POST -d '{
    "stocks" : [{
    	"length" : "60",
    	"width" : "40",
    	"count": "10",
    	"grainDirection": null
    },{
    	"length" : "40",
    	"width" : "35",
    	"grainDirection": null
    }],
    "requirements" : [{
    	"length" : "30", 
    	"width" : "20", 
        "count": "8",
    	"grainDirection": null
    },
    {
    	"width" : "20", 
    	"length" : "20", 
        "count": "3",
    	"grainDirection": null
    }],
	"settings" : {
	"kerf": "0"
	}
}' https://api.opticutter.com/v1/panel

Response

Response object contains a single solution object, which contains three inner child elements: totalRequiredStocks field, array of requiredStocks and array of layouts objects. Again, solution object is very similar to sheet/panel cutting plan solution from our online application. Take a short look at the sheet cutting plan results in online application first to understand it's concept.
Response object description
For the sake of clarity, the table below do not contains solution wrapper object.
totalRequiredStocks
integer, required
Total sum of all required stocks.
requiredStocks
array, required
Array of all required stocks and it's counts. Every child object contains four fields: index, length, width and count.
index
integer, required
Order index of stock panel from request's stocks array.
length
string, required
Length of the relevant stock panel.
Additional information only.
width
string, required
Width of the relevant stock panel.
Additional information only.
count
integer, required
Number of required stocks.
layouts
array, required
Array of all cut layouts. Every child object contains four objects: count field, stock object, panels array and remainders object.
count
integer, required
Number of repetitions of this layout. ("Repetition" value in online application)
stock
single element, required
Stock element used in this layout.
index
integer, required
Order index of stock element from request's stocks array.
length
string, required
Length of the relevant stock.
Additional information only.
width
string, required
Width of the relevant stock.
Additional information only.
panels
array, required
A list of all panels that can be cut in this layout. Every child object contains five mandatory fields: index, length, width, initial coordinates x and y and one optional field label.
index
integer, required
Order index of required panel from request's requirements array.
length
string, required
Required panel length. Length is always in horizontal direction.
Note to placement
width
string, required
Required panel width. Width is always in vertical direction.
Note to placement
x
string, required
X-coordinate (horizontal axis) of the panel's location on the stock sheet.
y
string, required
Y-coordinate (vertical axis) of the panel's location on the stock sheet.
label
string, optional
Label of the required panel from request's requirements array.
Additional information only
remainders
array, optional
A list of all remainders in current layout. Every child object contains four fields: length, width and initial coordinates x and y.
length
string, required
Remainder panel length. Length is always in horizontal direction.
Note to placement
width
string, required
Remainder panel width. Width is always in vertical direction.
Note to placement
x
string, required
X-coordinate (horizontal axis) of the remainder's location on the stock sheet.
y
string, required
Y-coordinate (vertical axis) of the remainder's location on the stock sheet.
cuts
single element, required
Information object. Holds info about cuts for this layout.
count
integer, required
The number of cuts in this layout.
length
string, required
The length of cuts in this layout.
svgImage
base64 string, optional
Cut layout scheme as SVG image encoded into base64 string. After decoding you got plain-text SVG image which can be processed by your API client.
Example response
{
	"solution": {
		"totalRequiredStocks": 4,
		"requiredStocks": [
			{
				"index": 0,
				"length": "60",
				"width": "40",
				"count": 1
			},
			{
				"index": 1,
				"length": "40",
				"width": "35",
				"count": 3
			}
		],
		"layouts": [
			{
				"count": 1,
				"stock": {
					"index": 0,
					"length": "60",
					"width": "40"
				},
				"panels": [
					{
						"index": 1,
						"length": "20",
						"width": "20",
						"x": "0",
						"y": "0"
					},
					{
						"index": 0,
						"length": "30",
						"width": "20",
						"x": "0",
						"y": "20"
					},
					{
						"index": 0,
						"length": "30",
						"width": "20",
						"x": "30",
						"y": "20"
					},
					{
						"index": 1,
						"length": "20",
						"width": "20",
						"x": "20",
						"y": "0"
					},
					{
						"index": 1,
						"length": "20",
						"width": "20",
						"x": "40",
						"y": "0"
					}
				],
				"remainders": null,
				"cuts": {
		          "count": 4,
		          "length": "120"
		        }
			},
			{
				"count": 3,
				"stock": {
					"index": 1,
					"length": "40",
					"width": "35"
				},
				"panels": [
					{
						"index": 0,
						"length": "20",
						"width": "30",
						"x": "0",
						"y": "0"
					},
					{
						"index": 0,
						"length": "20",
						"width": "30",
						"x": "20",
						"y": "0"
					}
				],
				"remainders": [
					{
						"length": "40",
						"width": "5",
						"x": "0",
						"y": "30"
					}
				],
		        "cuts": {
		          "count": 2,
		          "length": "70"
		        }
			}
		]
	}
}
Graphical representation of the solution from example response above

Notes

As you can see on the picture, "blue" panels (index: 0) are placed horizontally (length: 30, width: 20) on the first layout, but vertically (length: 20, width: 30) on the second layout.
Zero-point coordinates (0, 0) are always in upper left corner of the stock sheet.
result

Status

Provides account status info.
Example request
curl -H "Content-type: application/json" \
	  -H "Authorization: Bearer <TOKEN>" \
	  -X POST http://api.opticutter.com/v1/status
Example response
{
	"message": "OK",
	"remaining": 4959
}
Field remaining contains info, how many API calls remains for this biling period. The same info is available also in API status section in online application.
api calls

Usage-based billing

The value can also be a negative number. Negative number means you spent all your API calls included in subscription package and you are currently spending additional calls, that will be billed at the end of the current billing period on the additional invoice.

Additional API call are billed in groups of 100 rounded down, e.g. 99 or less additional API calls are free, 199 calls are billed as 100, etc.

Errors

If something goes wrong, we will return an error to you. Here is the list of common errors you could receive. Element source (when not null) contains detailed information which JSON element contains invalid data.

Invalid or missing authorization token
{
	"errors": [
		{
			"status": "401",
			"source": null,
			"title": "Unauthorized",
			"detail": "Authorization header is missing or invalid."
		}
	]
}
Invalid number format in JSON request
{
	"errors": [
		{
			"status": "422",
			"source": {
				"pointer": "settings.kerf"
			},
			"title": "Validation failed",
			"detail": "Invalid decimal or fractional number"
		}
	]
}
Missing mandatory data in JSON request
{
	"errors": [
		{
			"status": "422",
			"source": {
				"pointer": "stocks[0].length"
			},
			"title": "Validation failed",
			"detail": "Must not be blank."
		}
	]
}
Lack of stocks
The supplied stock is too small to accept all the required parts.
{
	"errors": [
		{
			"status": "422",
			"source": {
				"pointer": "stocks"
			},
			"title": "Validation failed",
			"detail": "Lack of stocks! Please add more stock's quantity or leave at least one stock quantity field blank."
		}
	]
}
Internal Server Error
This is not your fault. Something broke on our servers. We will try to fix it ASAP.
{
	"errors": [
		{
			"status": "500",
			"source": null,
			"title": "Internal Server Error",
			"detail": "Identifier: 1643996842483"
		}
	]
}