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)

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.

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