BrainCircuits.io API - Getting Started

The BrainCircuits.io API allows access to datasets via its REST API interface.

Obtaining Access Tokens

You can obtain your BrainCircuits.io access token by signing into the BrainCircuits.io application and opening the Profile widget using the tab bar on the right. The field BrainCircuits.io Access Token contains your access token for the API.

If you want to access projects that are managed by the CAVE infrastructure (such as fruitfly_fafb_flywire for the FAFB/FlyWire project, or fruitfly_fanc_cave for the FANC project), you will also need to set the CAVE token in the Profile widget, and use it in the API requests.

Accessing information from the API with Python

We can access the REST API using the requests package.

import requests

We need to provide the access tokens.

# Copy-Paste Token from Profile Widget on braincircuits.io/app
bcio_access_token = ""
cave_access_token = ""

We specify a list of segments of interest.

segments = [720575940634474894,720575940630280234]

Different projects can have different sets of properties associated with segments. The following list gives a list of commonly used properties

• size: the size of a segment, as number of voxels or some volumetric metric (such as um**3)
• link_pre: information about the presynaptic sites of a neuron, and statistics on downstream partner neurons
• link_post: information about the postsynaptic sites of a neuron, and statistics on upstream partner neurons
• neurotransmitter: information about (predicted) neurotransmitter types
• connectivity: upstream and downstream partner neurons together with synaptic counts
• nucleus: information about the nucleus of a cell
• soma: information about the soma of a cell
• mitochondria: information about the mitochondria of a cell
• dcv: information about the dense-core vesicles of a cell

We can use these properties to retrieve information about segments in a specific project.

We use the link_pre property in the fruitfly_fafb_flywire project as an example:

prop = "link_pre"
project = "fruitfly_fafb_flywire"
req = requests.post(f'https://api.braincircuits.io/circuit/segment/property/{property}',
    headers={
        'Authorization': 'Bearer {}'.format(bcio_access_token),
        'Authorization-Cave': 'Bearer {}'.format(cave_access_token)
    },
    params={
        'project': project
    },
    json={
        "segments": segments,
    })

We then retrieve the information as JSON object and display the results:

res = req.json()
print(res)

The result may look like:

{'materialized_timestamp': 1677042002,
 'results': {
    '720575940630280234': {
        'nr_pre': 1880,
        'nr_downstream_partner': 848
    },
    '720575940634474894': {
        'nr_pre': 3847, 
        'nr_downstream_partner': 1772
    }
}}

For projects with ongoing proofreading and changes of segments, the information is updated frequently (usually in hourly intervals), and the materialized_timestamp indicates the UNIX timestamp in seconds of the last update timepoint.

An example output of the connectivity property may look like:

{'downstream': [
    {'segmentid': '720575940620173737', 'synaptic_count': 60},
    {'segmentid': '720575940620777382', 'synaptic_count': 42},
    {'segmentid': '720575940660210817', 'synaptic_count': 37},
  ...],
 'upstream': [
    {'segmentid': '720575940612097522', 'synaptic_count': 70},
    {'segmentid': '720575940632227921', 'synaptic_count': 64},
    {'segmentid': '720575940623566788', 'synaptic_count': 32},
  ...]
}