WORK IN PROGRESS | Services are in active development and are subject to change

The Remote Job Submission API enables integration of Charity Engine as a backend service and provides functions for managing the entire lifecycle of jobs submitted to the network.

See Computing with Charity Engine for a contextual overview of the Charity Engine ecosystem (including additional interfaces such as Remote CLI, Ethereum Smart Contract, and Ethereum Dapp).


General Usage

The endpoint for all calls is: 

Server-side implementation is in active development and may change.

The endpoint accepts a JSON payload within a POST request, unless otherwise specified.

Also see External APIs, which lists APIs that the Remote API is able to call.

API definition

External APIs (draft)

Charity Engine can call the following API endpoints upon circumstances outlined in this document. An HTTP POST request with JSON payload will be dispatched to a URL hosted by the compute provider or other external services.

HTTP Basic authorization for API endpoint URLs is supported.


When compute capacity is purchased on the Charity Engine marketplace, Charity Engine can call a compute provider’s API endpoint to launch reserved compute capacity.


ComputeCapacity[] capacity // List of ComputeCapacity objects, one per instance type that is being reserved.
float duration // Maximum number of hours the compute capacity is reserved for. Compute payloads may exit early. 

Expected results

int count // Number of successfully launched instances.
string error // Error message, if any. Optional.

Testing + Troubleshooting

Testing via CURL

To use cURL to submit a job from a .json file:

$ curl -v "content-type: application/json" -d @example-job-create.json

Contents of the POST data (example-job-create.json file):

  "commandLine":"math 2+2 > output/out.txt",
  "specs": {
    "ram": 512,
    "disk": 512,
    "networkDownload": 0,
    "networkUpload": 0
  "hours": 1,
  "inputFiles": [
      "filename": "in.txt",
      "url": ""


If trouble occurs on the execution node, it can be helpful to set the useOwnDevices parameter to true during job-create. This causes the job to be given to a node operated by the account that submitted the job, rather than sending it out to other qualified nodes in the Charity Engine device pool.

The useOwnDevices parameter requires signing up as a Charity Engine volunteer and having a running client.

  • No labels