API Examples#

GraphQL Playground#

If you visit the OpenNeuro API endpoint in a browser, you can write queries with an interactive tool. This will automatically use your OpenNeuro account for authentication if you have recently authenticated with OpenNeuro on the web.

GraphQL basics#

A basic introduction to GraphQL can be found in the official documentation.

GraphQL divides operations into queries, mutations, and a few more rarely used types like subscriptions. A query will return the same result if repeated, mutations will take some action that will be reflected in future queries.

OpenNeuro has several top level types with many fields available to query. Most information is available under the Dataset and Snapshot types.

Example Queries#

Query dataset information#

For a specific dataset you can query fields available for the draft or snapshots programmically.

query {
  dataset(id: "ds000224") {
    id
    name
  }
}

Result:

{
  "data": {
    "dataset": {
      "id": "ds000224",
      "name": "The Midnight Scan Club (MSC) dataset"
    }
  }
}

Root level fields for datasets are either top level metadata (does not belong to any draft or snapshot) or automatically determined from the most recent snapshot (such as the dataset name in this example).

To obtain this information from a particular snapshot, snapshots can be queried in several ways. This example gets the DatasetDOI field from dataset_description.json as of the 1.0.1 snapshot.

query {
  snapshot(datasetId: "ds000224", tag: "1.0.1") {
    id
    tag
    description {
      Name
      DatasetDOI
    }
  }
}
{
  "data": {
    "snapshot": {
      "id": "ds000224:1.0.1",
      "tag": "1.0.1",
      "description": {
        "Name": "The Midnight Scan Club (MSC) dataset",
        "DatasetDOI": "10.18112/openneuro.ds000224.v1.0.1"
      }
    }
  }
}

Snapshot Creation#

You can create a snapshot of the current draft with a mutation. Each argument provided in the changes array will become a line in the CHANGES file entry for this new snapshot.

mutation {
  createSnapshot(
    datasetId: "ds000001"
    tag: "1.2.0"
    changes: ["Added new subject", "Subject metadata corrections"]
  ) {
    id
  }
}

Obtain dataset file trees#

File trees are represented as git tree objects. There is a root tree for each version (commit or tag) that can be obtained by requesting the default file listing.

query snapshotFiles {
  snapshot(datasetId: "ds000001", tag: "1.0.0") {
    files {
      id
      key
      filename
      size
      directory
      annexed
    }
  }
}

This will return a listing of files at the top level of the dataset.

{
  "data": {
    "snapshot": {
      "files": [
        {
          "id": "92e695a42470f48ad581ac8dd0894c07ebc4a9b8",
          "key": "87b0d1e84b52af82a50100edc269f5c24e4caba5",
          "filename": "CHANGES",
          "size": 273,
          "directory": false,
          "annexed": false
        },
        {
          "id": "c1905b369e84cbb3016022ebf1ea1574087e20c2",
          "key": "d8ced4c2adedad6d69c264f94a71df6be20a2241",
          "filename": "README",
          "size": 807,
          "directory": false,
          "annexed": false
        },
        {
          "id": "7293821ae8d5c647351cb2a31484162097a442c4",
          "key": "8f6598628c1e0938397e9a3994ba71416a674f9b",
          "filename": "dataset_description.json",
          "size": 150,
          "directory": false,
          "annexed": false
        },
        {
          "id": "10834f1acb4897eaed5b29fc642718451100721b",
          "key": null,
          "filename": "sub-01",
          "size": 0,
          "directory": true,
          "annexed": false
        }
      ]
    }
  }
}

In this example, you can see that sub-01 has the "directory": true. This means the directory id field can be used to retrieve additional trees.

query snapshotFiles {
  snapshot(datasetId: "ds000001", tag: "1.0.0") {
    files(tree: "10834f1acb4897eaed5b29fc642718451100721b") {
      id
      key
      filename
      size
      directory
      annexed
    }
  }
}

This will return any files below sub-01 in the tree for this version.

{
  "data": {
    "snapshot": {
      "files": [
        {
          "id": "c63eeb1e0f41fea629f34269025f9d8225a2f3ff",
          "key": null,
          "filename": "anat",
          "size": 0,
          "directory": true,
          "annexed": false
        },
        {
          "id": "309cd8eae8896096c8734b024ac52be4743c9f44",
          "key": null,
          "filename": "func",
          "size": 0,
          "directory": true,
          "annexed": false
        }
      ]
    }
  }
}

The full tree can be retrieved by recursively following tree objects.