Getting Started

This guide walks you through installing the Flywheel software development kit (SDK), authenticating with your Flywheel instance, and making your first API calls.

Prerequisites

Before you begin, ensure you have the following:

• Python 3.10 or later: Verify your version by running python --version.
• Basic Python knowledge: For a refresher, see the Python Tutorial.
• A Flywheel account with appropriate permissions: You must have access to at least one project to follow the examples in this guide. See the Flywheel permissions documentation for details on roles and access levels.

Installation

Use a virtual environment

Using a virtual environment keeps SDK dependencies isolated from other Python projects on your system. This is optional but highly recommended for package management.

The following commands create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install via pip

Install the SDK from the Python Package Index (PyPI) using pip:

pip install flywheel-sdk

Verify the installation

Confirm the SDK installed correctly:

python -c "import flywheel; print(flywheel.__version__)"

Update an existing installation

To upgrade to the latest version:

pip install --upgrade flywheel-sdk

Authentication

The SDK requires access to your Flywheel instance. You can authenticate using stored command-line interface (CLI) credentials or by providing an application programming interface (API) key directly.

Generate an API key

To authenticate with an API key, first generate one in the Flywheel web interface. See Create an API key for step-by-step instructions.

Connection methods

Using CLI credentials

If you have logged in with the Flywheel CLI, the SDK can use those stored credentials automatically, without needing to specify the API key explicitly in the Python script.

fw = flywheel.Client()

Using an API key directly

Pass your API key as a string argument to connect:

fw = flywheel.Client(api_key="your-api-key")

Using an environment variable

Store your API key as an environment variable to avoid hardcoding credentials in your scripts. This is the recommended method for ensuring that your API key is not exposed.

export FW_API_KEY="your-api-key"

import os

fw = flywheel.Client(api_key=os.environ.get("FW_API_KEY"))

Your First Request

The following complete example connects to Flywheel and retrieves information about the currently authenticated user to verify the connection is working.

import os
import flywheel

# Create a client using an environment variable
fw = flywheel.Client(api_key=os.environ.get("FW_API_KEY"))

# Retrieve the currently authenticated user
current_user = fw.get_current_user()
print(f"Connected as: {current_user.firstname} {current_user.lastname}")
print(f"User ID: {current_user.id}")

If the connection is successful, you will see your name and user ID printed to the console. An ApiException on this call typically indicates an invalid API key; ensure that the API key was saved correctly to the environment variable and that the API key has not expired.

Basic Operations Walkthrough

The following examples demonstrate the most common SDK operations. Each example assumes you have an active flywheel.Client instance as fw.

Find a project

The projects finder can be used to find projects you have access to:

all_projects = fw.projects()

print("Flywheel Projects:")
for project in all_projects:
    print(f"\t{project.label}")

The Flywheel SDK provides multiple methods for specifying the scope of the returned projects. For example, the find_first method searches for the first matching object:

# Update `group_id` and `project_label` to match a project you have access to
group_id = "my_group"
project_label = "My Project"
project = fw.projects.find_first(f"group={group_id},label={project_label}")
print(f"Found project: {project.label} (ID: {project.id})")

List subjects in a project

Once you have a project object, iterate over its subjects:

print(f"{project.label} Subjects:")
for subject in project.subjects.iter():
    print(f"\t{subject.label}")

Access container attributes and metadata

Container objects expose standard attributes directly and store custom metadata in a dictionary under info. With the same project object as you found before, investigate some of the available attributes:

print(f"{project.label} Attributes and Metadata:")

# Standard attributes
print(f"Label:    {project.label}")
print(f"ID:       {project.id}")
print(f"Created:  {project.created}")
print(f"Modified: {project.modified}")

# Custom metadata
print(f"Info: {project.info}")

Upload a file

The SDK allows for programmatically uploading and downloading files from Flywheel. First, create a test file to be uploaded. Then, pass the filepath as an argument to upload_file() and upload:

new_upload = project.upload_file("data.csv")
# upload_file() returns a list of file objects.
print(f"Uploaded {new_upload[0].name} to {project.label}")

Download a file

Download a single file from the project to a local path, passing arguments for the filename as stored on Flywheel and where you want the file to be saved locally:

project.download_file("data.csv", "/tmp/data.csv")

Understanding the Response

Container object structure

When you retrieve a container, the SDK returns a Python object whose fields you can access as attributes.

Attributes vs. info

Each container has two categories of data:

• Attributes: Standard fields defined by Flywheel, such as id, label, created, and modified. These are consistent across all containers of the same type.
• Info: A free-form dictionary of custom metadata attached to the container by users or gears. Access it via container.info.

Common attributes

Some common attributes that are available on all project, subject, session, and acquisition containers include:

Reload a container

A container object is a snapshot of the data at the time of retrieval. After making changes, or when you need to confirm the latest server state, call reload() to fetch a fresh copy:

project = project.reload()

Next Steps

Now that you have made your first API calls, use the following resources to go deeper:

• Core Concepts: Learn foundational SDK techniques for interacting with Flywheel with in-depth examples to put your learning into practice.
• API Reference: Browse complete method documentation for all SDK classes and functions.