Kernel API

  • Updated on Apr 17, 2025
  • Published on Sep 24, 2024
Prev Next

The Kernel API allows you to automate repeated tasks programmatically.

To get started, have your Organization Owner generate an API key on the Organization Settings page.

External/Customer facing API

Routes for:

  • All dataset IDs + metadata in a study
  • Run a pipeline, given a dataset ID and pipeline name
  • Status for most recent pipeline run and signed urls if present, given dataset ID and pipeline name

NOTE:

All routes use the same hostname: api.kernel.com
Each route requires an API key in the header, such as:
headers={"Authorization": f"{api_key}"}
Python
An Organization Owner can generate an API key on the Organization Settings page.

Common ways to use Kernel API

To find yourstudy_id:

Navigate to the study in portal and notice the URL looks like:

https://portal.kernel.com/organizations/2d1fee1c-c2bc-4833-b560-afc673140f42/studies/b249e4b9-9108-4ce4-a7ce-41cc3bbd2bf2/datasets

The bold part b249e4b9-9108-4ce4-a7ce-41cc3bbd2bf2 is your study_id to use in the following routes.

List all dataset IDs and metadata in a study:

list_datasets(study_id : str)--> Dict[str, List[dict]]

/api/vi/study/{study_id}/datasets

  • Parameters:
    • study_id (str) - study id
  • Returns:
    • All dataset IDs and metadata in a study
  • Return Type:
    • Dict[str, List[dict]]
{
    "datasets": [
        {
            "id": "00000000000000000000000000000000",
            "meta": {}, # possible keys include "description", "name", "experiment"
            "participant": {
                "id": "00000000000000000000000000000000"
                "participant_id": "00000000000000000000000000000000"
                "created_at": 0.0, # seconds since epoch
                "active": True, # participant active status
                "pending": False, # participant pending status
                "status": "active" # participant status in the study,
            },
            "created_date": 0.0, # seconds since epoch
            "started_at": 0.0, # seconds since epoch
            "stopped_at": 0.0, # seconds since epoch
        } 
     ]
 }
JSON

Examples

>>> response = requests.get("https://api.kernel.com/api/v1/study/000000000000000/datasets")
>>> assert response.status_code == 200
>>> datasets = response.json()["datasets"]
>>> dataset_ids = [dataset["id"] for dataset in datasets]
Python

Available pipelines:

# Available pipelines are:
   "analysis_eeg"
   "analysis_nirs_epoched"
   "analysis_nirs_glm"
   "analysis_task"
   "qc_eeg"
   "qc_nirs_basic"
   "qc_nirs"
   "qc_syncbox"
   "reconstruction"
   "pipeline_snirf_gated"
   "snirf_hb_moments"
   "snirf_moments"
Python
NOTE:
See Kernel documentation for more information on each pipeline.

Get the status of the most recent pipeline run for a dataset and asset URLs if available:

pipeline_status(study_id : str, dataset_id: str, pipeline_name: str)

/api/vi/study/{study_id}/dataset/{dataset_id}/pipeline/{pipeline_name]/status

  • Parameters:     
    • study_id (str) - study id
    • dataset_id (str) - dataset id
    • pipeline_name (str) - pipeline name
  • Returns: 
    • Status of the most recent pipeline run and asset URLs if available 
  • Return Type:
    • dict
{
       "job_id": "00000000000000000000000000000000",
       "status": "SUCCEEDED",
       "signed_urls": {
           "urls": {
               "filename1": "https://someurl"
           }, "sizes": {
               "filename1": 123.1
           },
           "batch_job_id": "00000000000000000000000000000000"
           "execution_id": "00000000000000000000000000000000"
       }
}
JSON

Examples

>>> response = requests.get("https://api.kernel.com/api/v1/study/000000000000000/dataset/000000000000000/pipeline/name/status")
>>> assert response.status_code == 200
>>> status = response.json()
>>> assert status["status"] == "SUCCEEDED"
Python

Run a pipeline for a dataset:

run_pipeline(study_id : str, dataset_id: str, pipeline_name: str) --> Dict[str, Any]

/api/vi/study/{study_id}/dataset/{dataset_id}/pipeline/{pipeline_name}

  • Parameters:     
    • study_id (str) - study id
    • dataset_id (str) - dataset id
    • pipeline_name (str) - pipeline name
  • Returns: 
    • Job ID if the pipeline run 
  • Return Type:
    • Dict
Response json structure:
{
       "job_id": "00000000000000000000000000000000"
}
JSON

Examples

>>> response = requests.post("https://api.kernel.com/api/v1/study/00000000000000/dataset/00000000000000/pipeline/name")
>>> assert response.status_code == 200
>>> job_id = response.json()["job_id"]
Python


                                                        

    


                                                        

    


.