Problems
API - Quickstart

This tutorial will show you how to start using the Problems module API. For detailed information about the available API methods go to the Problems module API documentation.

Important: To successfully go through this tutorial you need to have a working Sphere Engine account with a dedicated API endpoint and API token. Register for a Sphere Engine account by filling in the sign-up form.

Step 1: Accessing the data

The Sphere Engine Problems API is available at:

https://<customer_id>.problems.sphere-engine.com/api/v4
To call any API method, you need to be authenticated with an API token that you can generate in the token manager section of the Sphere Engine client panel.

Check the correctness of the API authentication using the /test method:

https://<customer_id>.problems.sphere-engine.com/api/v4/test?access_token=<access_token>

Step 2: Creating a submission

The following example shows how to call the API method responsible for creating a new submission using the curl command.

curl -X POST \
    -F "problemId=1" \
    -F "compilerId=1" \
    -F "source=@prog.cpp" \
    "https://<customer_id>.problems.sphere-engine.com/api/v4/submissions?access_token=<access_token>"

Alternatively, you can use any application or programming language that allows you to use HTTP queries. In the example above, we decided to use the curl command due to its simplicity and availability in UNIX-like systems.

The presented example sends a program written in C++ (i.e., compilerId = 1) that will be executed as a solution the programming problem of id=1 (i.e., problemId = 1).

In response, the unique identifier of the submission will be returned, for example:

{
  "id": 42
}

Note: To see what programming languages are supported by Problems module and what are their unique IDs, please refer to the supported programming languages article.

Step 3: Checking the result

After sending your submission, wait a while for it to be executed. While waiting for the execution, you can check its current status at intervals of a few seconds (learn more).

To receive the result of the submission, use the appropriate API method and submission identifier (here 42). The following example also uses the curl command:

curl "https://<customer_id>.problems.sphere-engine.com/api/v4/submissions/42?access_token=<access_token>"

Detailed information about the application and judging results will be returned. An example response has the following structure:

{
  "id": 42,
  "executing": false,
  "date": "2018-02-05 10:02:26 +00:00",
  "compiler": {
    "id": 1,
    "name": "C++",
    "version": {
      "id": 1,
      "name": "gcc 6.3"
    }
  },
  "problem": {
    "id": 1,
    "code": "TEST",
    "name": "Life, Universe and Everything",
    "uri": "..."
  },
  "result": {
    "status": {
      "code": 14,
      "name": "wrong answer"
    },
    "score": 0,
    "time": 0.01,
    "memory": 2048,
    "signal": 0,
    "streams": {
      "source": {
        "size": 189,
        "uri": "..."
      },
      "output": {
        "size": 11,
        "uri": "..."
      },
      "error": null,
      "cmpinfo": null,
      "debug": {
        "size": 96,
        "uri": "..."
      }
    },
    "testCases": [
      {
        "number": 0,
        "status": {
          "code": 14,
          "name": "wrong answer"
        },
        "score": 0,
        "time": 0.01,
        "memory": 2048,
        "signal": 0
      }
    ]
  }
}
  Contents