GCAPI 0.14.0 - breaking changes

Published 25 Nov. 2025

A new version for GCAPI has been released: 0.14.0. While we think that every change in software has the potential to be breaking for a user, we believe this new version merits a special warning: breaking changes!

When uploading data, GCAPI no longer guesses what the user wants. Rather, it now allows the user to explicit name the upload source for the socket value. The sources for building a case should now be wrapped in the new SocketValueSpec.

We've also taken the opportunity to improve consistency in the naming of methods and arguments and have carried out some renaming.

We highly recommend looking at the migration section below to get to grips with what has changed. For more detailed information, see the GitHub release page or the extended documentation.

Migration Guide

Required: SocketValueSpec wrapping

Wrapping values with a SocketValueSpec object is now required for uploading. This prevents GCAPI from guessing what the value to upload should be and prevents nasty surprises or cryptic error messages.

Each SocketValueSpec defines a socket slug and exactly one source:

  • file (singular, e.g. "path/to/file.json")
  • files(multiple e.g. ["1.dcm", "2.dcm"])
  • value
  • existing_image_api_url
  • existing_socket_value

Removed: upload_cases

The old and deprecated upload_cases is now fully removed. Please use one of the newer ones that are specifically meant for archives or reader studies.

Renamed: methods and arguments

Renaming of helper functions: they are now singular and require you to loop over the different cases instead of providing a list of cases. Note the missing 's' in some of the functions:

  • add_cases_to_archive → add_case_to_archive
  • add_cases_to_reader_study → add_case_to_reader_study
  • run_external_job → start_algorithm_job

In addition, the keyword arguments have been renamed for consistency:

  • archive → archive_slug
  • reader_study → reader_study_slug
  • algorithm → algorithm_slug
  • archive_items → values (list of SocketValueSpecs)
  • display_sets → values (list of SocketValueSpecs)

Example

Old version:
client.add_cases_to_archive(
  archive="ai_corads", 
  archive_items=[
    [
      {"socket_1": "/path/to/file.json"},
      {"socket_2": "An elegant prompt"}
    ]
  ],
)
New version:
from gcapi import SocketValueSpec

client.add_case_to_archive(
  archive_slug="ai_corads", 
  values=[
      SocketValueSpec(
        socket_slug="socket_1", 
        file="/path/to/file.json",
      ),
      SocketValueSpec(
        socket_slug="socket_2",
        value="An elegant prompt"
      )
  ],
)

Authors

Tags