Skip to main content

00. jinko-sdk usage

How to use the jinko-sdk library​

The jinko-sdk library provides a typed Python client to simplify the use of Jinko's API, which is designed for trial simulation and design optimization. Jinko is an innovative SaaS and CaaS platform that offers programmatic access to a wide range of functionalities, facilitating integration with various tools and enhancing collaboration.

Migrating an older notebook?

If your code still uses import jinko_helpers as jinko and jinko.make_request(...), see the Migration Guide for a side-by-side mapping to the new API described below.

Installation​

To install the jinko-sdk library, you can use either pip or poetry:

pip install jinko-sdk

or

poetry add jinko-sdk

If you're using an AI coding assistant, the Jinko Skills repository provides ready-made skills that help set up and use the SDK correctly. We recommend installing the skills before you start using the API.

About the SDK​

Starting with jinko-sdk 1.0.0, the package is imported as jinko and is built around a single entry point, JinkoClient, plus typed domain objects for each kind of project item you work with (Model, Vpop, ProtocolDesign, SimpleOutputSet, AdvancedOutputSet, Trial, DataTable, Calibration, ...). Instead of building raw HTTP requests by hand, you call typed methods on the client or on the objects it returns.

The JinkoClient​

Creating a client​

from jinko import JinkoClient

client = JinkoClient()

By default the client reads its credentials from environment variables (JINKO_API_KEY, JINKO_PROJECT_ID, and optionally JINKO_BASE_URL).

See 01. Authenticate for details and for passing credentials explicitly.

Working with project items​

Most JinkoClient methods follow the same shape across resource types (models, vpops, protocol designs, output sets, trials, data tables, calibrations, ...):

  • client.get_<resource>(sid, revision=None): fetch a single typed object by its short ID.
  • client.list_<resource>s(name=..., folder=..., limit=..., after=...): fetch one page of results.
  • client.iter_<resource>s(name=..., folder=...): iterate over all matching results, handling pagination for you.
  • client.create_<resource>_from_json(json_content, ...): create a project item from a raw JSON payload, for cases without a higher-level helper (for example client.create_model_from_json(...)).

Each returned object exposes common metadata through properties such as .sid, .core_id, .snapshot_id, .name, and .url, plus resource-specific action methods (for example trial.run() or vpop.statistics()).

For anything the typed client doesn't cover yet, client.raw_request(method, path, ...) sends a request with only the authentication headers added.

This is to be used only when no typed method exists.

Searching and navigating​

results = client.search(text="my model", types=["ComputationalModel"])

See 02. Navigate and Search for more.