Set up a new project

Create a project to group your cells, studies, models, and optimizations, then scope subsequent SDK calls to it.

A project groups your cell specifications, studies, models, and optimizations. Create one, then scope your work to it.

Install and authenticate first: pip install ionworks-api and set IONWORKS_API_KEY. See the Python API client page.

from ionworks import Ionworks

client = Ionworks()

# Create a project — its id groups everything you do next.
project = client.project.create({
    "name": "NMC Characterization",
    "description": "Q1 2025 NMC cell testing",
})
print(project.id)

# Find projects later (name is a case-insensitive substring match).
projects = client.project.list(name="NMC", order_by="created_at", order="desc")

# Studies live inside a project — pass its id to scope the call.
study = client.study.create(
    {"name": "1C Discharge Study"},
    project_id=project.id,
)

What’s happening

• Two ways to scope work to a project: pass the project id explicitly per call (e.g. client.study.create(project_id, ...)), or set IONWORKS_PROJECT_ID in your environment so it becomes the default for calls whose project_id is optional.
• client.project has the full CRUD set: .list(), .get(id), .create(data), .update(id, data), .delete(id).
• Projects and studies have no create_or_get. For re-runnable scripts, catch the CONFLICT error and read existing_id from its detail to reuse an existing one.

Learn more

• Projects & studies
• Organizations
• Python API client — project_id argument and IONWORKS_PROJECT_ID precedence