API docs by Redocly

adiutaOpt (v8.4.0)

Download OpenAPI specification:

adiutaByte GmbH: info@adiutabyte.de URL: https://adiutabyte.de

Introduction

Welcome to the adiutaOpt API documentation!

This document specifies all endpoints and schema requirements. If you notice an error, please contact us.

The typical process of an optimization request looks as follows:

  • Obtain authentication tokens
  • Use authentication tokens to post an input data set to the optimization request endpoint. If everything is in order, a key will be returned that has to be stored
    • If the request was rejected, check authentication details and schema. The return code and data will give some hints as to what needs to be fixed.
  • Use the authentication token and the key on the solution endpoint to request the solved data.
    • If the plan is still in calculation, wait until it's done
    • If the calculation has finished, store the solution
  • Check if the calculation could be carried out or if an error was returned (see ErrorPlan as possible return data of the solution endpoint)

The overview site can be found here.

Deployment Status

Deployment status data is available only on PROD/DEV/EXP documentation.

Authentication

How to authenticate before any request.

AWS Cognito

The authentication is performed via AWS Cognito (Developer-Guide). It is recommended to use one of the SKDs provided by AWS to simplify the authentication process considerably. Examples for SDKs:

Configuration

  • Used protocol: Secure Remote Password Protocol
  • User pool data:
    • UserPoolId/ClientId is available only on PROD/DEV/EXP documentation.
  • Username/Password are provided when signing up for an account. If you don't have an account, please contact us.

Tokens

Authentication provides three tokens: the access-token, the ID-token and the refresh-token. All three are JSON Web Tokens.

  • The access-token is currently not used in the API.
  • The ID-token has to be proposed in every request in the header as follows:

Authorization: 'ID-token'

  • The ID-token contains a timestamp when the token has been authorized (auth_time) and when it will expire (exp). Currently, an ID-token expires after one hour and requests with expired ID-tokens are rejected automatically. You can get a new ID-token by using the refresh-token without having to re-enter your credentials.

Request samples 

const user = "";        // your username
const pw = "";          // your password
const userPoolID = "";  // UserPoolID, see configuration details
const clientID = "";    // ClientId, see configuration details

const AmazonCognitoIdentity = require('amazon-cognito-identity-js');

module.exports.login = () => new Promise((resolve, reject) => {

  const userPool = new AmazonCognitoIdentity.CognitoUserPool({
    UserPoolId: userPoolID,
    ClientId: clientID
  });

  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
      Username: user,
      Password: pw,
  });

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser({
      Username: user,
      Pool: userPool
  });

  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result) {
        const token = result.getIdToken().getJwtToken();
        resolve(token);
    },
    onFailure: function (err) {
        reject();
    }
  });
})

Request Analytics

Obtain request meta data for analytics

Get request overview

Get an overview over each client's requests in the specified year/month. Management-users without reporter status can access only those requests that have been sent by a correlating user-account (identical authentication mail address). Requesting data for any other customer will result in status code 403 - FORBIDDEN. You can find out your customer id by checking the field requestID in a response of a GET /plan/... request.

Management users with reporter status can access the request data for any customer. Requesting data for a non-existent customer will result in a 200 response with empty RequestResponse as data.

Responses from this endpoint have a content size limit which depends on the used content-type of the response, which can be specified with the accept header. If the response size would exceed that limit, the endpoint returns code 409 instead. Responses of type application/json can include payloads of up to 6Mb, all other types can return up to 4.5Mb of (compressed) data.

Authorizations:
BearerAuth
path Parameters
customer
required
string

The customer ID to collect analytics from. It is the first part of the requestID contained in optimization solutions.

year
required
string

Year to collect analytics to, allowed formats are 'YYYY' and 'YY', the latter of which assumes the 21st century.

month
required
string

Month to collect analytics to, allowed formats are 'MM' and 'M'.

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Request samples 

curl \
  --request GET \
  --url '[see url above]/[your customer id]/[YYYY]/[MM]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
[
  • {
    }
]

Get request overview (Preflight)

path Parameters
customer
required
string

Can be anything

year
required
string

Can be anything

month
required
string

Can be anything

Responses

Get request overview (header-only)

Same behavior as the GET request but returns no content for any of the responses.

path Parameters
customer
required
string

The customer ID to collect analytics from. It is the first part of the requestID contained in optimization solutions.

year
required
string

Year to collect analytics to, allowed formats are 'YYYY' and 'YY', the latter of which assumes the 21st century.

month
required
string

Month to collect analytics to, allowed formats are 'MM' and 'M'.

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Limit Usage

Obtain limit usage data to evaluate against set limits.

Get request statistics to compare against usage limits

Get an overview over each client's limit usages on each day in the specified year/month. Management-users without reporter status can access only those requests that have been sent by a correlating user-account (identical authentication mail address). Requesting data for any other customer will result in status code 403 - FORBIDDEN. You can find out your customer id by checking the field requestID in a response of a GET /plan/... request.

Management users with reporter status can access the limit usage for any customer. Requesting data for a non-existent customer will result in a 200 response with empty LimitResponse as data.

Responses from this endpoint have a content size limit which depends on the used content-type of the response, which can be specified with the accept header. If the response size would exceed that limit, the endpoint returns code 409 instead. Responses of type application/json can include payloads of up to 6Mb, all other types can return up to 4.5Mb of (compressed) data.

Authorizations:
BearerAuth
path Parameters
customer
required
string

The customer ID to collect analytics from. It is the first part of the requestID contained in optimization solutions.

year
required
string

Year to collect analytics to, allowed formats are 'YYYY' and 'YY', the latter of which assumes the 21st century.

month
required
string

Month to collect analytics to, allowed formats are 'MM' and 'M'.

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Request samples 

curl \
  --request GET \
  --url '[see url above]/[your customer id]/[YYYY]/[MM]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
[
  • {
    }
]

Get request statistics to compare against usage limits (Preflight)

path Parameters
customer
required
string

Can be anything

year
required
string

Can be anything

month
required
string

Can be anything

Responses

Get Solution (header-only)

Same behavior as the GET request but returns no content for any of the responses.

path Parameters
customer
required
string

The customer ID to collect analytics from. It is the first part of the requestID contained in optimization solutions.

year
required
string

Year to collect analytics to, allowed formats are 'YYYY' and 'YY', the latter of which assumes the 21st century.

month
required
string

Month to collect analytics to, allowed formats are 'MM' and 'M'.

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Index

List of all schema definitions

Integer_u32

integer (Integer_u32) [ 0 .. 2147483647 ]

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

2147483647

RequestsEntryMixed

timestamp
required
string

Timestamp when the request was posted.

type
required
string
Value: "tour"
tasks
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks in request.

workers
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of workers in request.

{
  • "timestamp": "2025-02-04T14:58:33.442Z",
  • "type": "tour",
  • "tasks": 2147483647,
  • "workers": 2147483647
}

RequestsEntryShift

timestamp
required
string

Timestamp when the request was posted.

type
required
string
Value: "shift"
tasks
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks in request.

workers
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of workers in request.

{
  • "timestamp": "2025-02-04T14:58:33.442Z",
  • "type": "shift",
  • "tasks": 2147483647,
  • "workers": 2147483647
}

RequestsEntryFloor

timestamp
required
string

Timestamp when the request was posted.

type
required
string
Value: "floor"
tasks
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks in request.

workers
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of workers in request.

{
  • "timestamp": "2025-02-04T14:58:33.442Z",
  • "type": "floor",
  • "tasks": 2147483647,
  • "workers": 2147483647
}

RequestResponseEntry

clientID
required
string

Identifier for the client. Mirrors the value of clientID in a request sent with the corresponding authentication. If a request has no clientID set, it gets marked down under "self-managed".

required
Array of RequestsEntryMixed (object) or RequestsEntryShift (object) or RequestsEntryFloor (object)

A list of all requests of this client and some analytics data

{
  • "clientID": "string",
  • "requests": [
    ]
}

LimitResponseEntry

10
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the tenth of the specified month.

11
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the eleventh of the specified month.

12
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the twelfth of the specified month.

13
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 13th of the specified month.

14
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 14th of the specified month.

15
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 15th of the specified month.

16
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 16th of the specified month.

17
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 17th of the specified month.

18
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 18th of the specified month.

19
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 19th of the specified month.

20
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 20th of the specified month.

21
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 21st of the specified month.

22
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 22nd of the specified month.

23
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 23rd of the specified month.

24
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 24th of the specified month.

25
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 25th of the specified month.

26
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 26th of the specified month.

27
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 27th of the specified month.

28
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 28th of the specified month.

29
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 29th of the specified month.

30
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 30th of the specified month.

31
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 31st of the specified month.

clientID
required
string

Identifier for the client. Mirrors the value of clientID in a request sent with the corresponding authentication. If a request has no clientID set, it gets marked down under "self-managed".

01
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the first of the specified month.

02
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the second of the specified month.

03
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the third of the specified month.

04
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the fourth of the specified month.

05
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the fifth of the specified month.

06
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the sixth of the specified month.

07
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the seventh of the specified month.

08
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the eighth of the specified month.

09
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the ninth of the specified month.

{
  • "10": 2147483647,
  • "11": 2147483647,
  • "12": 2147483647,
  • "13": 2147483647,
  • "14": 2147483647,
  • "15": 2147483647,
  • "16": 2147483647,
  • "17": 2147483647,
  • "18": 2147483647,
  • "19": 2147483647,
  • "20": 2147483647,
  • "21": 2147483647,
  • "22": 2147483647,
  • "23": 2147483647,
  • "24": 2147483647,
  • "25": 2147483647,
  • "26": 2147483647,
  • "27": 2147483647,
  • "28": 2147483647,
  • "29": 2147483647,
  • "30": 2147483647,
  • "31": 2147483647,
  • "clientID": "string",
  • "01": 2147483647,
  • "02": 2147483647,
  • "03": 2147483647,
  • "04": 2147483647,
  • "05": 2147483647,
  • "06": 2147483647,
  • "07": 2147483647,
  • "08": 2147483647,
  • "09": 2147483647
}

LimitResponse

Array
10
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the tenth of the specified month.

11
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the eleventh of the specified month.

12
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the twelfth of the specified month.

13
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 13th of the specified month.

14
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 14th of the specified month.

15
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 15th of the specified month.

16
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 16th of the specified month.

17
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 17th of the specified month.

18
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 18th of the specified month.

19
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 19th of the specified month.

20
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 20th of the specified month.

21
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 21st of the specified month.

22
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 22nd of the specified month.

23
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 23rd of the specified month.

24
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 24th of the specified month.

25
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 25th of the specified month.

26
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 26th of the specified month.

27
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 27th of the specified month.

28
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 28th of the specified month.

29
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 29th of the specified month.

30
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 30th of the specified month.

31
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the 31st of the specified month.

clientID
required
string

Identifier for the client. Mirrors the value of clientID in a request sent with the corresponding authentication. If a request has no clientID set, it gets marked down under "self-managed".

01
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the first of the specified month.

02
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the second of the specified month.

03
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the third of the specified month.

04
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the fourth of the specified month.

05
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the fifth of the specified month.

06
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the sixth of the specified month.

07
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the seventh of the specified month.

08
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the eighth of the specified month.

09
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of tasks requested on the ninth of the specified month.

[
  • {
    }
]

Changelog

v7.17.0

  • Added accept and accept-encoding headers to all GET endpoints, added 406, 409 response codes

v7.8.0

  • Added section Index which contains all major schema defintions

v7.7.0

  • Updated 4xx and 5xx http responses with content documentation

v7.6.0

  • Added missing HEAD request documentation to GET endpoints

v7.5.0

  • Added response code 405 to all endpoints

v7.4.1

  • Updated changelog to only include changes related to the corresponding site.

v7.4.0

  • Added analytics documentation page