REST Resources

The Solver API primarily manages two types of resources: problem resources and solver resources. The following table provides an overview of the SAPI URLs that map to resources.

Table 23 SAPI URLs
URL Method Reference
/problems/ POST Submit Problem
/problems/ DELETE Cancel Multiple Problems
/problems/<problem_id> DELETE Cancel a Problem by ID
/problems/[?id=id1,id2] GET List Problems
/problems/<problem_id>/ GET Get Problem
/problems/<problem_id>/answer/ GET Get Problem Answer
/problems/<problem_id>/messages/ GET Get Problem Messages
/solvers/remote/ GET List Solvers
/solvers/remote/<solver_id>/ GET Get Solver Configuration

Problem Resource

A problem resource represents a problem submitted by a user to a solver. This may be a problem submitted via the API or a web-based front-end. See also the Data Encoding chapter to understand the supported data types for problems and solutions.

Problem Lifecycle

A problem may have one of the following statuses:

Table 24 Problem Status
Status Description
PENDING Problem was submitted and is queued for processing.
IN_PROGRESS Problem is currently being processed.
COMPLETED Problem completed successfully.
FAILED Problem processing failed.
CANCELLED Problem was cancelled.

Note

If a quota is reached before a problem is processed, the problem remains in a PENDING state until the quota resets or the problem expires.

Diagram showing how a problem status changes from pending to in progress to one of the terminal states. The terminal states are cancelled, completed, or failed.

Fig. 51 Initially a problem is in the PENDING state. When the D-Wave system starts to process a problem, its state changes to IN_PROGRESS. After completion, the problem status changes to either COMPLETED or FAILED (if an error occurred). COMPLETED, FAILED, and CANCELLED are all terminal states. After a problem enters a terminal state, its status does not change. Users can cancel a problem at any time before it reaches its terminal state.

Submit Problem

Request

To submit problems, send an HTTP POST request to $SAPI_HOME/problems/. The POST request body should contain JSON-encoded problem information. When possible, if you have more than one problem, submit them in a single query.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"solver": "c4-sw_sample", "data": "128 3\n48 48 -1\n52 52 1\n48 52 -1",
"type": "ising", "params": {"num_reads": 123}}]'

Problem Data

The JSON data for the submitted problem must contain the following properties:

Table 25 Key-Value Pairs for Submit Problem Request
Key Value
solver Solver to be used.
data Problem data; see the Data Encoding section.
type One of the supported problem types (ising or qubo).
params Solver-specific parameters.

Note

The allowed problem types are listed in the solver’s properties.

Response

The system returns a list with the results to the corresponding problems in the JSON request.

Error in problem (example):

{
    "error_code": 400,
    "error_msg": "Missing parameter 'num_reads' in problem JSON"
}
Table 26 Key-Value Pairs for Submit Problem Response with Error
Key Value
error_code Error code describing the type of error encountered; 400 for missing parameters, 403 for no access to solver, 429 for too many requests.
error_msg Message describing the error encountered

Successful completion (example):

{
    "status": "COMPLETED",
    "earliest_estimated_completion": "2018-08-13T20:47:03.009543Z",
    "solved_on": "2018-08-13T20:47:03.066239Z",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-08-13T20:47:03.009343Z",
    "answer": {
        "num_variables": 128,
        "format": "qp",
        "energies": "zczMzMzMDMA=",
        "num_occurrences": "CgAAAA==",
        "active_variables": "AAAAAAEAAAACAAAABAAAAA==",
        "solutions": "sA==",
        "timing": {}
        },
    "latest_estimated_completion": "2018-08-13T20:47:03.009543Z",
    "type": "ising",
    "id": "d8b0a7d0-01e5-4d27-bae2-93cd23f3204c"
  }

Completion with errors (example):

{
    "status": "FAILED",
    "solved_on": "2018-01-18T10:26:00.020954",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-01-18T10:25:59.941674",
    "type": "ising",
    "id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b",
    "error_message": "Some error message"
}
Table 27 Key-Value Pairs for Submit Problem Responses
Key Value
answer Content of the answer depends on the solver and parameters used. See Data Encoding for Solutions for more details about the structure of this field.
earliest_estimated_completion Estimated completion time: beginning of range.
error_message Error message generated by the system if problem status is FAILED.
id Unique identifier of the problem; can be used later to retrieve problem information, the answer, and the messages.
latest_estimated_completion Estimated completion time: end of range.
solved_on If this problem is in terminal state (COMPLETED, CANCELLED or FAILED) it shows the time when problem was solved. Empty otherwise.
status One of the problem states as defined in Problem Lifecycle.
submitted_on The time when problem was submitted.
type Problem type as specified when the problem was submitted.

Cancel Multiple Problems

Request

To cancel PENDING problems, send an HTTP DELETE request to $SAPI_HOME/problems/. The request body should be a JSON-encoded list of problem IDs; if the request body is empty, the request has no effect. When possible, if you have more than one problem to cancel, submit them in a single query.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems/id=792749f9-3bbc-4eea-84da-e51726ac0be6,id2,id3 -X DELETE

Response

The system returns a list with the results to the corresponding problems in the JSON request in one of the following formats.

Error in problem (example):

{
    "error_code": 409,
    "error_msg": "Problem already terminated"
}

Response codes are as follows:

Table 28 Response Codes for Cancel Problem
Response Code Meaning
200 Success.
202 Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete.
404 Problem with the specified ID does not exist.
409 Problem reached one of terminal states before the call.
429 Number of API requests exceeds the permitted limit.
Table 29 Key-Value Pairs for Cancel Problem Response with Error
Key Value
error_code Error code describing the type of error encountered
error_msg Message describing the error encountered

Successful cancellation (example):

{
    "status": "CANCELLED",
    "solved_on": "2018-01-18T10:26:00.020954",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-01-18T10:25:59.941674",
    "type": "ising",
    "id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b"
}
Table 30 Key-Value Pairs for Cancel Problem Response
Key Value
id Unique identifier of the problem.
status Problem state: CANCELLED.
submitted_on The time when problem was submitted.
solved_on The time when problem was cancelled.
type Problem type as specified when the problem was submitted.

Cancel a Problem by ID

Request

To cancel a previously submitted problem, make an HTTP DELETE request to $SAPI_HOME/problems/.

$SAPI_HOME/problems/<problem_id>/

Response

The system returns the problem formatted as a JSON object.

Example of the output:

{
    "status": "CANCELLED",
    "solved_on": null,
    "solver": "C4_19091607.17_C6",
    "submitted_on": "2018-01-18T10:06:10.025064",
    "type": "ising",
    "id": "894fb8e7-4176-4b39-92f4-10ad56432f09"
}

Response codes are as follows:

Table 31 Response Codes for Cancel Problem
Response Code Meaning
200 Success.
202 Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete.
404 Problem with the specified ID does not exist.
409 Problem reached one of terminal states before the call.
429 Number of API requests exceeds the permitted limit.

List Problems

Request

To retrieve a list of previously submitted problems, make an HTTP GET request to $SAPI_HOME/problems/ with a parameter id that contains a comma-separated list of problem IDs to SAPI URI:

$SAPI_HOME/problems/?id=0b759042-726e-4665-b04b-3b42e1ed0b01, 80387b7a-0976-43da-8ed0-e7a27821c177

Response

The system returns problems as a JSON list.

Example of the output:

[
    {
        "status": "COMPLETED",
        "solved_on": "2012-12-05T19:15:04+00:00",
        "solver": "SR8",
        "submitted_on": "2012-12-05T19:06:57+00:00",
        "type": "ising",
        "id": "0b759042-726e-4665-b04b-3b42e1ed0b01"
    },
    {
        "status": "COMPLETED",
        "solved_on": "2012-12-05T19:15:07+00:00",
        "solver": "SR8",
        "submitted_on": "2012-12-05T19:06:57+00:00",
        "type": "ising",
        "id": "80387b7a-0976-43da-8ed0-e7a27821c177"
    }
]

Response codes are as follows:

Table 32 Response Codes for List Problem
Response Code Meaning
200 Response contains valid problems list.
404 Problem with specified ID does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem

Request

To retrieve a previously submitted problem, make an HTTP GET request to $SAPI_HOME/problems/:

$SAPI_HOME/problems/<problem_id>/

When possible, if you want more than one problem, submit the request in a single query.

Response

When a problem is solved, the system includes the specified problem formatted as a JSON object in its response.

Example of the output:

{
    "status": "PENDING",
    "solved_on": null,
    "solver": "4.7_C4_19091607.17_C6",
    "submitted_on": "2018-01-18T10:06:10.025064",
    "type": "ising",
    "id": "894fb8e7-4176-4b39-92f4-10ad56432f09"
}

Response codes are as follows:

Table 33 Response Codes for Get Problem
Response Code Meaning
200 Success
404 Problem with specified ID does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem Answer

Request

To retrieve an answer for the problem, make an HTTP GET request to $SAPI_HOME/problems/:

$SAPI_HOME/problems/<problem_id>/answer/

Response

When a problem is solved, the system returns the problem answer formatted as a JSON object, or 404 if none exists.

Below is an example of a JSON-encoded problem answer in a response message:

{
    "answer": {
        "format": "qp",
        "num_variables": 1152,
        "solutions": "AwEAAg==",
        "energies": "gBSuR+F6lL+AFK5H4XqUv4AUrkfhepS/gBSuR+F6lL8=",
        "active_variables": "AQAAAAQAAAA=",
        "num_occurrences": "AwAAAAIAAAACAAAAAwAAAA==",
        "timing": {
        }
    }
}

See the Data Encoding for Solutions section for a list of the key-value pairs returned in the response.

Response codes are as follows:

Table 34 Response Codes for Get Problem Answer
Response Code Meaning
200 Success.
404 Answer for the problem does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem Messages

Request

To retrieve messages for a problem, make an HTTP GET request to $SAPI_HOME/problems/.

$SAPI_HOME/problems/<problem_id>/messages/

Response

The system returns messages formatted as a JSON object or 404 if an incorrect problem ID is specified. If there are no messages, an empty list is returned.

Example of the output:

[
    {
        "timestamp": "2011-06-06T14:24:40.393751",
        "message": "Internal SAPI error occurred.",
        "severity": "ERROR"
    }
]

Response codes are as follows:

Table 35 Response Codes for Get Problem Messages
Response Code Meaning
200 Success.
404 Problem does not exist.
429 Number of API requests exceeds the permitted limit.

Solvers Resource

A solver instance represents a logical solver that can be one of:

  • QPAPI solver
  • Subgraph solver

Solver Resource Properties

Table 36 Solver Resource Properties
Property Description
description Description of the solver.
property Solver properties such as supported problem types, active qubits, active couplers, total number of qubits, and so on.
id Unique ID of the solver.

For details on solver types, solver properties, and the problem-solving parameters that are supported by the different solver types, see the D-Wave Solver Properties and Parameters: Reference Guide.

List Solvers

Request

Retrieve the list of supported remote solvers by sending an HTTP GET request to $SAPI_HOME/solvers/. This example uses curl to retrieve the list of remote solvers:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/solvers/remote

Response

The system responds with 200 OK and returns list of solvers formatted as a JSON list.

Example of the output:

[
    {
        "properties": {
            "supported_problem_types": ["qubo", "ising"],
            "qubits": [ ... ],
            "couplers": [ ... ],
            "num_qubits": 512
        }
        "id": "Solver 1",
        "description": "Solver #1"
    },
    {
        "properties": {
            "supported_problem_types": ["ising"],
            "qubits": [ ... ],
            "couplers": [ ... ],
            "num_qubits": 512
        }
        "id": "Solver 2",
        "description": "Solver #2"
    }
]

Get Solver Configuration

Request

Retrieve the configuration of a solver by sending an HTTP GET request to $SAPI_HOME/solvers/. This example uses curl to retrieve the configuration of a remote solver:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/solvers/remote/solver1

Response

The system returns solver configuration formatted as a JSON object.

Example of the output:

{
    "properties": {
        "supported_problem_types": ["qubo", "ising"],
        "qubits": [ ... ],
        "couplers": [ ... ],
        "num_qubits": 512
    }
    "id": "solver1",
    "description": "solver1"
}

The properties attribute holds the solver properties such as number of active qubits and couplers.

Response codes are as follows:

Table 37 Response Codes for Get Solver Configuration
Response Code Meaning
200 Success
404 Solver with specified solver_id does not exist.
429 Number of API requests exceeds the permitted limit.