General

Authentication

There are 4 user access levels:

User type

Access level

Administrator

admin

Planner

plan

Shop team

shop

Auditor

audit

All REST API requests must be authenticated by providing the Authorization header in the format Authorization: Bearer API_KEY, where API_KEY is one of a user’s generated API keys.

Request conventions

  • Requests containing JSON bodies must include the Content-Type: application/json header.

  • Setting the Accept: application/json header will cause the server to return HTTP errors as a JSON object with an error field instead of as an HTML page.

  • The JSON bodies of PATCH requests should be JSON objects whose keys are any subset of the fields of the type of object they are patching. Unknown fields will be silently ignored, and a log message will be printed for each field the current user cannot write.

  • Query parameters are all optional unless otherwise noted.

  • The following values are considered “true” for boolean parameters, and all others are considered “false”:

    • 1

    • true

    • on

    • yes

    • y

    • checked

  • Dates should always be in YYYY-MM-DD format

  • Times should always be in HH:MM (24-hour clock) format

  • Timestamps (date and time together) should always be in UTC as UNIX timestamps (using floating point numbers for sub-second precision is allowed, but not required)

Automatic string to number conversion

As of server version 4.10.22, providing a string value for a numeric (int or float) object field in an edit (PATCH) request is handled according to the following rules:

  • If string is empty (""):

    • Optional (nullable) fields will be set to NULL.

    • Required (non-nullable) fields will be set to 0.

  • If string is not empty:

    • The string value will be parsed as the field’s numeric type.

    • Parse errors will cancel the request and return an error message.

    • Floating-point numbers in strings will fail to parse for integer fields.

Examples:

Field type

Data type

String value

Result

Optional

(any)

""

NULL

Required

""

0

(any)

(any)

"text"

(error)

int

"123"

123

"123.4"

(error)

float

"123"

123

"123.4"

123.4

Response conventions

  • Responses containing JSON bodies will include the Content-Type: application/json header

  • Responses to requests that create or modify objects will contain the new object in their body.

  • Errors will result in a 4xx (client error) or 5xx (server error) response code and a body with a JSON object containing at least an error field with a short, user-presentable error message detailing the problem.

  • For errors occurring when an action requires a higher user level than the current login, a second allowed field will be present containing an array of users who are allowed to perform that action.

  • Date+time values are returned as UNIX timestamps (UTC) with decimal milliseconds that can be safely truncated to integers for most applications.

  • Unless specified otherwise, endpoints will return 200 OK on success.

Server language support

To change the language used in responses, set the Accept-Language header to a supported language. As of server version 4.10.5, the following languages are supported:

  • English (en)

  • Spanish (es)

  • German (de)

  • Italian (it)

Requesting an unsupported language will cause the server to return responses in English. For supported languages, any strings not available in the selected language will be returned in English.

Numbers in JSON will always be formatted in compliance with the JSON specification, but numbers in HTML pages may be formatted according to the conventions of the selected language.

Time zone support

The server will use the local time zone set by the timezone global option when handling HTTP requests.

The X-Timezone header can be set to the IANA name of the client’s time zone to change this for a single request.

Internal server errors

When status 500 is reported, you may wish to check the Content-Disposition header. If it starts with attachment, the response body is a support file that can be sent to Wolfram Manufacturing for troubleshooting.

Root endpoints

GET /api/

Check API access.

Example response
 {
     "application": "OnTakt",
     "version": "4.8.7",
     "user": {
         "access_level": "admin",
         "username": "admin"
     }
 }

Returns the version of OnTakt and the currently authenticated access level.

POST /api/restart

Restart OnTakt.

Status Codes:
POST /api/backup

Perform a database backup.

Status Codes:
Returns:

the resulting dump as a file download