9.1 OptServer REST API

9.1.1 Commands

This section describes the REST API of the OptServer. Additional authentication options, common to all commands, are described in Sec. 9.1.2 (Authentication).

POST /api/submit

Submit a problem to the server.

The problem file should be submitted in the content of the request. The Content-Type header should specify the file format of the submission (if not present, the solver may guess incorrect format and fail to start the solver). The recognized content types are listed in Table 9.1.

Table 9.1 Content types in submit.

Content-Type

File format

application/x-mosek-task

MOSEK Task

application/x-mosek-json

MOSEK JTask (JSON)

application/x-mosek-lp

LP format

application/x-mosek-mps

MPS format

application/x-mosek-opf

OPF format

application/x-mosek-cbf

CBF format

application/x-mosek-ptf

PTF format

application/x-mosek-XXX+gzip

XXX format compressed with gzip

application/x-mosek-XXX+zstd

XXX format compressed with zstd

See Sec. 10 (Supported File Formats) for descriptions of supported formats.

The name of the job can be specified in a query string jobname=....

On response OK a token identifying the problem is returned in the response body, in the session cookie and in the header X-Mosek-Token. That token is required to identify the job in future request.

GET /api/solve

Start solving and wait for the solver to finish.

The job to start is specified in the query string token=...

The file format of the solution can be specified in the Accept header (if not present, a plain text ASCII solution will be returned), as in Table 9.2.

The solution is returned as the content of the response and the headers are set as in Table 9.3.

POST /api/submit+solve

Submit a problem to the server and get the solution.

Performs the actions of submit and solve in one request. The problem file should be submitted in the content of the request. The Content-Type header should specify the file format of the submission (if not present, the solver may guess incorrect format and fail to start the solver). The recognized content types are listed in Table 9.1.

See Sec. 10 (Supported File Formats) for descriptions of supported formats.

The file format of the solution can be specified in the Accept header (if not present, a plain text ASCII solution will be returned), as in Table 9.2. The solution is returned as the content of the response and the headers are set as in Table 9.3.

The name of the job can be specified in a query string jobname=....

On response OK a token identifying the problem is returned in the header X-Mosek-Token. That token is required to identify the job in future request.

GET /api/solve-background

Start solving in the background and return immediately.

The job to start is specified in the query string token=...

It returns OK if the solver started successfully.

GET /api/solution

Return the solution

The problem whose solution is requested is specified in the query string token=....

The file format of the solution can be specified in the Accept header (if not present, a plain text ASCII solution will be returned). The recognized types are:

Table 9.2 Accepted solution formats in solution and solve.

Accept

Solution format

application/x-mosek-task

MOSEK Task

application/x-mosek-json

MOSEK JSol file (JSON)

application/json

MOSEK JSol file (JSON)

text/plain

Plain text

See Sec. 10 (Supported File Formats) for descriptions of supported solution formats.

If the solution is not yet available, the call returns an empty response with no content.

If the solution is available it is returned as the content of the response and the following headers are set:

Table 9.3 Headers set in the response to solution and solve.

Header

Value

Content-Type

Solution type as requested in Accept

X-Mosek-Res-Code

Response code from the optimizer

X-Mosek-Trm-Code

Termination code from the optimizer

X-Mosek-Token

Job token

Content-Length

Length of the solution

If an unexpected error occurred then X-Mosek-Res-Code will be set to MSK_RES_UNKNOWN and the other fields are not defined.

GET /api/log

Return the log.

The problem for which the log output is requested is specified in the query string token=....

If the query string contains the parameter offset=XXXX, the log file will be returned from offset XXXX until the end of what is currently available. Otherwise the whole log is returned.

GET /api/break

Attempt to terminate the solver.

The problem to be terminated is specified in the query string token=....

9.1.2 Authentication

If the OptServer allows anonymous job submission then no authentication is required. Otherwise all of the commands require authentication in one of the following ways:

  • The user’s access token is passed as a query string access-token=... in the request.

  • The user’s access token is passed in the header X-Mosek-Access-Token of the request.

  • Through a session cookie, if the user has logged in and authenticated within an open session.

Access tokens for users can be generated through the Web GUI, see Sec. 8 (Web GUI interface).