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.