API v1 Reference

Aignostics Platform API v1.4.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Aignostics Platform is a cloud-based service that enables organizations to access advanced computational pathology applications through a secure API. The platform provides standardized access to Aignostics’ portfolio of computational pathology solutions, with Atlas H&E-TME serving as an example of the available API endpoints.

To begin using the platform, your organization must first be registered by our business support team. If you don’t have an account yet, please contact your account manager or email support@aignostics.com to get started.

More information about our applications can be found on https://platform.aignostics.com.

How to authorize and test API endpoints:

1. Click the “Authorize” button in the right corner below

2. Click “Authorize” button in the dialog to log in with your Aignostics Platform credentials

3. After successful login, you’ll be redirected back and can use “Try it out” on any endpoint

Note: You only need to authorize once per session. The lock icons next to endpoints will show green when authorized.

Base URLs:

• /api

Authentication

• oAuth2 authentication.

  • Flow: authorizationCode

  • Authorization URL = https://aignostics-platform-staging.eu.auth0.com/authorize

  • Token URL = https://aignostics-platform-staging.eu.auth0.com/oauth/token

Scope	Scope Description

Public

list_applications_v1_applications_get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/applications", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/applications',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/applications

List available applications

Returns the list of the applications, available to the caller.

The application is available if any of the versions of the application is assigned to the caller’s organization. The response is paginated and sorted according to the provided parameters.

Parameters

Name	In	Type	Required	Description
page	query	integer	false	none
page-size	query	integer	false	none
sort	query	any	false	Sort the results by one or more fields. Use + for ascending and - for descending order.

Detailed descriptions

sort: Sort the results by one or more fields. Use + for ascending and - for descending order.

Available fields:

• application_id

• name

• description

• regulatory_classes

Examples:

• ?sort=application_id - Sort by application_id ascending

• ?sort=-name - Sort by name descending

• ?sort=+description&sort=name - Sort by description ascending, then name descending

Example responses

200 Response

[
  {
    "application_id": "he-tme",
    "name": "Atlas H&E-TME",
    "regulatory_classes": [
      "RUO"
    ],
    "description": "The Atlas H&E TME is an AI application designed to examine FFPE (formalin-fixed, paraffin-embedded) tissues stained with H&E (hematoxylin and eosin), delivering comprehensive insights into the tumor microenvironment.",
    "latest_version": {
      "number": "1.0.0",
      "released_at": "2025-09-01T19:01:05.401Z"
    }
  },
  {
    "application_id": "test-app",
    "name": "Test Application",
    "regulatory_classes": [
      "RUO"
    ],
    "description": "This is the test application with two algorithms: TissueQc and Tissue Segmentation",
    "latest_version": {
      "number": "2.0.0",
      "released_at": "2025-09-02T19:01:05.401Z"
    }
  }
]

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A list of applications available to the caller	Inline
401	Unauthorized	Unauthorized - Invalid or missing authentication	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

Status Code 200

Response List Applications V1 Applications Get

Name	Type	Required	Restrictions	Description
Response List Applications V1 Applications Get	[ApplicationReadShortResponse]	false	none	[Response schema for List available applications and Read Application by Id endpoints]
» ApplicationReadShortResponse	ApplicationReadShortResponse	false	none	Response schema for List available applications and Read Application by Id endpoints
»» application_id	string	true	none	Application ID
»» name	string	true	none	Application display name
»» regulatory_classes	[string]	true	none	Regulatory classes, to which the applications comply with. Possible values include: RUO, IVDR, FDA.
»» description	string	true	none	Describing what the application can do
»» latest_version	any	false	none	The version with highest version number available to the user

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	ApplicationVersion	false	none	none
»»»» number	string	true	none	The number of the latest version
»»»» released_at	string(date-time)	true	none	The timestamp for when the application version was made available in the Platform

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

read_application_by_id_v1_applications__application_id__get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/applications/{application_id}", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/applications/{application_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/applications/{application_id}

Read Application By Id

Retrieve details of a specific application by its ID.

Parameters

Name	In	Type	Required	Description
application_id	path	string	true	none

Example responses

200 Response

{
  "application_id": "he-tme",
  "name": "Atlas H&E-TME",
  "regulatory_classes": [
    "RUO"
  ],
  "description": "The Atlas H&E TME is an AI application designed to examine FFPE (formalin-fixed, paraffin-embedded) tissues stained with H&E (hematoxylin and eosin), delivering comprehensive insights into the tumor microenvironment.",
  "versions": [
    {
      "number": "1.0.0",
      "released_at": "2025-09-15T10:30:45.123Z"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	ApplicationReadResponse
403	Forbidden	Forbidden - You don’t have permission to see this application	None
404	Not Found	Not Found - Application with the given ID does not exist	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

application_version_details_v1_applications__application_id__versions__version__get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/applications/{application_id}/versions/{version}", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/applications/{application_id}/versions/{version}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/applications/{application_id}/versions/{version}

Application Version Details

Get the application version details.

Allows caller to retrieve information about application version based on provided application version ID.

Parameters

Name	In	Type	Required	Description
application_id	path	string	true	none
version	path	string	true	none

Example responses

200 Response

{
  "version_number": "0.4.4",
  "changelog": "New deployment",
  "input_artifacts": [
    {
      "name": "whole_slide_image",
      "mime_type": "image/tiff",
      "metadata_schema": {
        "type": "object",
        "$defs": {
          "LungCancerMetadata": {
            "type": "object",
            "title": "LungCancerMetadata",
            "required": [
              "type",
              "tissue"
            ],
            "properties": {
              "type": {
                "enum": [
                  "lung"
                ],
                "type": "string",
                "const": "lung",
                "title": "Type"
              },
              "tissue": {
                "enum": [
                  "lung",
                  "lymph node",
                  "liver",
                  "adrenal gland",
                  "bone",
                  "brain"
                ],
                "type": "string",
                "title": "Tissue"
              }
            },
            "additionalProperties": false
          }
        },
        "title": "ExternalImageMetadata",
        "$schema": "http://json-schema.org/draft-07/schema#",
        "required": [
          "checksum_crc32c",
          "base_mpp",
          "width",
          "height",
          "cancer"
        ],
        "properties": {
          "stain": {
            "enum": [
              "H&E"
            ],
            "type": "string",
            "const": "H&E",
            "title": "Stain",
            "default": "H&E"
          },
          "width": {
            "type": "integer",
            "title": "Width",
            "maximum": 150000,
            "minimum": 1
          },
          "cancer": {
            "anyOf": [
              false
            ],
            "title": "Cancer"
          },
          "height": {
            "type": "integer",
            "title": "Height",
            "maximum": 150000,
            "minimum": 1
          },
          "base_mpp": {
            "type": "number",
            "title": "Base Mpp",
            "maximum": 0.5,
            "minimum": 0.125
          },
          "mime_type": {
            "enum": [
              "application/dicom",
              "image/tiff"
            ],
            "type": "string",
            "title": "Mime Type",
            "default": "image/tiff"
          },
          "checksum_crc32c": {
            "type": "string",
            "title": "Checksum Crc32C"
          }
        },
        "description": "Metadata corresponding to an external image.",
        "additionalProperties": false
      }
    }
  ],
  "output_artifacts": [
    {
      "name": "tissue_qc:tiff_heatmap",
      "mime_type": "image/tiff",
      "metadata_schema": {
        "type": "object",
        "title": "HeatmapMetadata",
        "$schema": "http://json-schema.org/draft-07/schema#",
        "required": [
          "checksum_crc32c",
          "width",
          "height",
          "class_colors"
        ],
        "properties": {
          "width": {
            "type": "integer",
            "title": "Width"
          },
          "height": {
            "type": "integer",
            "title": "Height"
          },
          "base_mpp": {
            "type": "number",
            "title": "Base Mpp",
            "maximum": 0.5,
            "minimum": 0.125
          },
          "mime_type": {
            "enum": [
              "image/tiff"
            ],
            "type": "string",
            "const": "image/tiff",
            "title": "Mime Type",
            "default": "image/tiff"
          },
          "class_colors": {
            "type": "object",
            "title": "Class Colors",
            "additionalProperties": {
              "type": "array",
              "maxItems": 3,
              "minItems": 3,
              "prefixItems": [
                {
                  "type": "integer",
                  "maximum": 255,
                  "minimum": 0
                },
                {
                  "type": "integer",
                  "maximum": 255,
                  "minimum": 0
                },
                {
                  "type": "integer",
                  "maximum": 255,
                  "minimum": 0
                }
              ]
            }
          },
          "checksum_crc32c": {
            "type": "string",
            "title": "Checksum Crc32C"
          }
        },
        "description": "Metadata corresponding to a segmentation heatmap file.",
        "additionalProperties": false
      },
      "scope": "ITEM",
      "visibility": "EXTERNAL"
    }
  ],
  "released_at": "2025-04-16T08:45:20.655972Z"
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	VersionReadResponse
403	Forbidden	Forbidden - You don’t have permission to see this version	None
404	Not Found	Not Found - Application version with given ID is not available to you or does not exist	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

list_runs_v1_runs_get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/runs", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/runs

List Runs

List runs with filtering, sorting, and pagination capabilities.

Returns paginated runs that were submitted by the user.

Parameters

Name	In	Type	Required	Description
application_id	query	any	false	Optional application ID filter
application_version	query	any	false	Optional Version Name
external_id	query	any	false	Optionally filter runs by items with this external ID
custom_metadata	query	any	false	Use PostgreSQL JSONPath expressions to filter runs by their custom_metadata.
page	query	integer	false	none
page_size	query	integer	false	none
for_organization	query	any	false	Filter runs by organization ID. Available for superadmins (any org) and admins (own org only). When provided, returns all runs for the specified organization instead of only the caller’s own runs.
sort	query	any	false	Sort the results by one or more fields. Use + for ascending and - for descending order.

Detailed descriptions

custom_metadata: Use PostgreSQL JSONPath expressions to filter runs by their custom_metadata.

URL Encoding Required

Important: JSONPath expressions contain special characters that must be URL-encoded when used in query parameters. Most HTTP clients handle this automatically, but when constructing URLs manually, please ensure proper encoding.

Examples (Clear Format):

• Field existence: $.study - Runs that have a study field defined

• Exact value match: $.study ? (@ == "high") - Runs with specific study value

• Numeric comparison: $.confidence_score ? (@ > 0.75) - Runs with confidence score greater than 0.75

• Array operations: $.tags[*] ? (@ == "draft") - Runs with tags array containing “draft”

• Complex conditions: $.resources ? (@.gpu_count > 2 && @.memory_gb >= 16) - Runs with high resource requirements

Examples (URL-Encoded Format):

• Field existence: %24.study

• Exact value match: %24.study%20%3F%20(%40%20%3D%3D%20%22high%22)

• Numeric comparison: %24.confidence_score%20%3F%20(%40%20%3E%200.75)

• Array operations: %24.tags%5B*%5D%20%3F%20(%40%20%3D%3D%20%22draft%22)

• Complex conditions: %24.resources%20%3F%20(%40.gpu_count%20%3E%202%20%26%26%20%40.memory_gb%20%3E%3D%2016)

Notes

• JSONPath expressions are evaluated using PostgreSQL’s @? operator

• The $. prefix is automatically added to root-level field references if missing

• String values in conditions must be enclosed in double quotes

• Use && for AND operations and || for OR operations

• Regular expressions use like_regex with standard regex syntax

• Please remember to URL-encode the entire JSONPath expression when making HTTP requests

sort: Sort the results by one or more fields. Use + for ascending and - for descending order.

Available fields:

• run_id

• application_id

• version_number

• custom_metadata

• submitted_at

• submitted_by

• terminated_at

• termination_reason

Examples:

• ?sort=submitted_at - Sort by creation time (ascending)

• ?sort=-submitted_at - Sort by creation time (descending)

• ?sort=state&sort=-submitted_at - Sort by state, then by time (descending)

Example responses

200 Response

[
  {
    "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
    "application_id": "he-tme",
    "version_number": "0.4.4",
    "state": "PENDING",
    "output": "NONE",
    "termination_reason": "ALL_ITEMS_PROCESSED",
    "error_code": "SCHEDULER.ITEMS_WITH_ERROR_THRESHOLD_REACHED",
    "error_message": "Run canceled given errors on more than 10 items.",
    "statistics": {
      "item_count": 0,
      "item_pending_count": 0,
      "item_processing_count": 0,
      "item_user_error_count": 0,
      "item_system_error_count": 0,
      "item_skipped_count": 0,
      "item_succeeded_count": 0
    },
    "custom_metadata": {
      "department": "D1",
      "study": "abc-1"
    },
    "custom_metadata_checksum": "f54fe109",
    "submitted_at": "2019-08-24T14:15:22Z",
    "submitted_by": "auth0|123456",
    "terminated_at": "2024-01-15T10:30:45.123Z",
    "num_preceding_items_org": 0,
    "num_preceding_items_platform": 0,
    "scheduling": {
      "due_date": "2019-08-24T14:15:22Z",
      "deadline": "2019-08-24T14:15:22Z"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
404	Not Found	Run not found	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

Status Code 200

Response List Runs V1 Runs Get

Name	Type	Required	Restrictions	Description
Response List Runs V1 Runs Get	[RunReadResponse]	false	none	[Response schema for Get run details endpoint]
» RunReadResponse	RunReadResponse	false	none	Response schema for Get run details endpoint
»» run_id	string(uuid)	true	none	UUID of the application
»» application_id	string	true	none	Application id
»» version_number	string	true	none	Application version number
»» state	RunState	true	none	none
»» output	RunOutput	true	none	none
»» termination_reason	any	true	none	The termination reason of the run. When the run is not in TERMINATED state, the termination_reason is null. If all items of of the run are processed (successfully or with an error), then termination_reason is set to ALL_ITEMS_PROCESSED. If the run is cancelled by the user, the value is set to CANCELED_BY_USER. If the run reaches the threshold of number of failed items, the Platform cancels the run and sets the termination_reason to CANCELED_BY_SYSTEM.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	RunTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» error_code	any	true	none	When the termination_reason is set to CANCELED_BY_SYSTEM, the error_code is set to define the structured description of the error.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» error_message	any	true	none	When the termination_reason is set to CANCELED_BY_SYSTEM, the error_message is set to provide more insights to the error cause.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» statistics	RunItemStatistics	true	none	none
»»» item_count	integer	true	none	Total number of the items in the run
»»» item_pending_count	integer	true	none	The number of items in PENDING state
»»» item_processing_count	integer	true	none	The number of items in PROCESSING state
»»» item_user_error_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is USER_ERROR
»»» item_system_error_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SYSTEM_ERROR
»»» item_skipped_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SKIPPED
»»» item_succeeded_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SUCCEEDED
»» custom_metadata	any	false	none	Optional JSON metadata that was stored in alongside the run by the user

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» custom_metadata_checksum	any	false	none	The checksum of the custom_metadata field. Can be used in the PUT /runs/{run-id}/custom_metadatarequest to avoid unwanted override of the values in concurrent requests.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» submitted_at	string(date-time)	true	none	Timestamp showing when the run was triggered
»» submitted_by	string	true	none	Id of the user who triggered the run
»» terminated_at	any	false	none	Timestamp showing when the run reached a terminal state.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» num_preceding_items_org	any	false	none	How many Items from other Runs in the same Organization are due to begin processing before this Run’s next Item does.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» num_preceding_items_platform	any	false	none	How many Items from other Runs are due to begin processing before this Run’s next Item does.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» scheduling	any	false	none	Scheduling constraints set for this run.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	SchedulingResponse	false	none	Scheduling fields returned in run responses.
»»»» due_date	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»» deadline	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

Enumerated Values

Property	Value
state	PENDING
state	PROCESSING
state	TERMINATED
output	NONE
output	PARTIAL
output	FULL
anonymous	ALL_ITEMS_PROCESSED
anonymous	CANCELED_BY_SYSTEM
anonymous	CANCELED_BY_USER

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

create_run_v1_runs_post

Code samples

import requests

headers = {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.post("/api/v1/runs", headers=headers)

print(r.json())

const inputBody = '{
  "application_id": "he-tme",
  "version_number": "1.0.0-beta1",
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "scheduling": {
    "deadline": "2026-03-05T23:59:59Z",
    "due_date": "2026-03-04T23:59:59Z"
  },
  "items": [
    {
      "external_id": "slide_1",
      "input_artifacts": [
        {
          "download_url": "https://example-bucket.s3.amazonaws.com/slide1.tiff?signature=...",
          "metadata": {
            "checksum_base64_crc32c": "64RKKA==",
            "height_px": 87761,
            "media-type": "image/tiff",
            "resolution_mpp": 0.2628238,
            "specimen": {
              "disease": "LUNG_CANCER",
              "tissue": "LUNG"
            },
            "staining_method": "H&E",
            "width_px": 136223
          },
          "name": "input_slide"
        }
      ]
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /v1/runs

Initiate Run

This endpoint initiates a processing run for a selected application and version, and returns a run_id for tracking purposes.

Slide processing occurs asynchronously, allowing you to retrieve results for individual slides as soon as they complete processing. The system typically processes slides in batches. Below is an example of the required payload for initiating an Atlas H&E TME processing run.

Payload

The payload includes application_id, optional version_number, and items base fields.

application_id is the unique identifier for the application. version_number is the semantic version to use. If not provided, the latest available version will be used.

items includes the list of the items to process (slides, in case of HETA application). Every item has a set of standard fields defined by the API, plus the custom_metadata, specific to the chosen application.

Example payload structure with the comments:

{
    application_id: "he-tme",
    version_number: "1.0.0-beta",
    items: [{
        "external_id": "slide_1",
        "custom_metadata": {"project": "sample-study"},
        "input_artifacts": [{
            "name": "user_slide",
            "download_url": "https://...",
            "metadata": {
                "specimen": {
                  "disease": "LUNG_CANCER",
                  "tissue": "LUNG"
                },
                "staining_method": "H&E",
                "width_px": 136223,
                "height_px": 87761,
                "resolution_mpp": 0.2628238,
                "media-type":"image/tiff",
                "checksum_base64_crc32c": "64RKKA=="
            }
        }]
    }]
}

Parameter	Description
application_id required	Unique ID for the application
version_number optional	Semantic version of the application. If not provided, the latest available version will be used
items required	List of submitted items i.e. whole slide images (WSIs) with parameters described below.
external_id required	Unique WSI name or ID for easy reference to items, provided by the caller. The external_id should be unique across all items of the run.
input_artifacts required	List of provided artifacts for a WSI; at the moment Atlas H&E-TME receives only 1 artifact per slide (the slide itself), but for some other applications this can be a slide and a segmentation map
name required	Type of artifact; Atlas H&E-TME supports only "input_slide"
download_url required	Signed URL to the input file in the S3 or GCS; Should be valid for at least 6 days
specimen: disease required	Supported cancer types for Atlas H&E-TME (see full list in Atlas H&E-TME manual)
specimen: tissue required	Supported tissue types for Atlas H&E-TME (see full list in Atlas H&E-TME manual)
staining_method required	WSI stain bio-marker; Atlas H&E-TME supports only "H&E"
width_px required	Integer value. Number of pixels of the WSI in the X dimension.
height_px required	Integer value. Number of pixels of the WSI in the Y dimension.
resolution_mpp required	Resolution of WSI in micrometers per pixel; check allowed range in Atlas H&E-TME manual
media-type required	Supported media formats; available values are: image/tiff (for .tiff or .tif WSI), application/dicom (for DICOM ), application/zip (for zipped DICOM), and application/octet-stream (for .svs WSI)
checksum_base64_crc32c required	Base64-encoded big-endian CRC32C checksum of the WSI image

Response

The endpoint returns the run UUID. After that, the job is scheduled for the execution in the background.

To check the status of the run, call GET v1/runs/{run_id} endpoint with the returned run UUID.

Rejection

Apart from the authentication, authorization, and malformed input error, the request can be rejected when specific quota limit is exceeded. More details on quotas is described in the documentation

Body parameter

{
  "application_id": "he-tme",
  "version_number": "1.0.0-beta1",
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "scheduling": {
    "deadline": "2026-03-05T23:59:59Z",
    "due_date": "2026-03-04T23:59:59Z"
  },
  "items": [
    {
      "external_id": "slide_1",
      "input_artifacts": [
        {
          "download_url": "https://example-bucket.s3.amazonaws.com/slide1.tiff?signature=...",
          "metadata": {
            "checksum_base64_crc32c": "64RKKA==",
            "height_px": 87761,
            "media-type": "image/tiff",
            "resolution_mpp": 0.2628238,
            "specimen": {
              "disease": "LUNG_CANCER",
              "tissue": "LUNG"
            },
            "staining_method": "H&E",
            "width_px": 136223
          },
          "name": "input_slide"
        }
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	RunCreationRequest	true	none

Example responses

201 Response

{
  "run_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Responses

Status	Meaning	Description	Schema
201	Created	Successful Response	RunCreationResponse
400	Bad Request	Bad Request - Input validation failed	None
403	Forbidden	Forbidden - You don’t have permission to create this run	None
404	Not Found	Application version not found	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

get_run_v1_runs__run_id__get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/runs/{run_id}", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/runs/{run_id}

Get run details

This endpoint allows the caller to retrieve the current status of a run along with other relevant run details. A run becomes available immediately after it is created through the POST /v1/runs/ endpoint.

To download the output results, use GET /v1/runs/{run_id}/ items to get outputs for all slides. Access to a run is restricted to the user who created it.

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /v1/runs/ endpoint

Example responses

200 Response

{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "application_id": "he-tme",
  "version_number": "0.4.4",
  "state": "PENDING",
  "output": "NONE",
  "termination_reason": "ALL_ITEMS_PROCESSED",
  "error_code": "SCHEDULER.ITEMS_WITH_ERROR_THRESHOLD_REACHED",
  "error_message": "Run canceled given errors on more than 10 items.",
  "statistics": {
    "item_count": 0,
    "item_pending_count": 0,
    "item_processing_count": 0,
    "item_user_error_count": 0,
    "item_system_error_count": 0,
    "item_skipped_count": 0,
    "item_succeeded_count": 0
  },
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109",
  "submitted_at": "2019-08-24T14:15:22Z",
  "submitted_by": "auth0|123456",
  "terminated_at": "2024-01-15T10:30:45.123Z",
  "num_preceding_items_org": 0,
  "num_preceding_items_platform": 0,
  "scheduling": {
    "due_date": "2019-08-24T14:15:22Z",
    "deadline": "2019-08-24T14:15:22Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	RunReadResponse
403	Forbidden	Forbidden - You don’t have permission to see this run	None
404	Not Found	Run not found because it was deleted.	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

cancel_run_v1_runs__run_id__cancel_post

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.post("/api/v1/runs/{run_id}/cancel", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/cancel',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /v1/runs/{run_id}/cancel

Cancel Run

The run can be canceled by the user who created the run.

The execution can be canceled any time while the run is not in the terminated state. The pending items of a canceled run will not be processed and will not add to the cost.

When the run is canceled, the already completed items remain available for download.

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /runs/ endpoint

Example responses

202 Response

null

Responses

Status	Meaning	Description	Schema
202	Accepted	Successful Response	Inline
403	Forbidden	Forbidden - You don’t have permission to cancel this run	None
404	Not Found	Run not found	None
409	Conflict	Conflict - The Run is already cancelled	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

list_run_items_v1_runs__run_id__items_get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/runs/{run_id}/items", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/items',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/runs/{run_id}/items

List Run Items

List items in a run with filtering, sorting, and pagination capabilities.

Returns paginated items within a specific run. Results can be filtered by item_id, external_ids, custom_metadata, terminated_at, and termination_reason using JSONPath expressions.

JSONPath Metadata Filtering

Use PostgreSQL JSONPath expressions to filter items using their custom_metadata.

Examples:

• Field existence: $.case_id - Results that have a case_id field defined

• Exact value match: $.priority ? (@ == "high") - Results with high priority

• Numeric comparison: $.confidence_score ? (@ > 0.95) - Results with high confidence

• Array operations: $.flags[*] ? (@ == "reviewed") - Results flagged as reviewed

• Complex conditions: $.metrics ? (@.accuracy > 0.9 && @.recall > 0.8) - Results meeting performance thresholds

Notes

• JSONPath expressions are evaluated using PostgreSQL’s @? operator

• The $. prefix is automatically added to root-level field references if missing

• String values in conditions must be enclosed in double quotes

• Use && for AND operations and || for OR operations

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /v1/runs/ endpoint
item_id__in	query	any	false	Filter for item ids
external_id__in	query	any	false	Filter for items by their external_id from the input payload
state	query	any	false	Filter items by their state
termination_reason	query	any	false	Filter items by their termination reason. Only applies to TERMINATED items.
custom_metadata	query	any	false	JSONPath expression to filter items by their custom_metadata
page	query	integer	false	none
page_size	query	integer	false	none
sort	query	any	false	Sort the items by one or more fields. Use + for ascending and - for descending order.

Detailed descriptions

sort: Sort the items by one or more fields. Use + for ascending and - for descending order. Available fields:

• item_id

• external_id

• custom_metadata

• terminated_at

• termination_reason

Examples:

• ?sort=item_id - Sort by id of the item (ascending)

• ?sort=-external_id - Sort by external ID (descending)

• ?sort=custom_metadata&sort=-external_id - Sort by metadata, then by external ID (descending)

Example responses

200 Response

[
  {
    "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
    "external_id": "slide_1",
    "custom_metadata": {},
    "custom_metadata_checksum": "f54fe109",
    "queue_position_org": 0,
    "queue_position_platform": 0,
    "state": "PENDING",
    "output": "NONE",
    "termination_reason": "SUCCEEDED",
    "error_code": "string",
    "error_message": "This item was not processed because the threshold of 3 items finishing in error state (user or system error) was reached before the item was processed.",
    "terminated_at": "2024-01-15T10:30:45.123Z",
    "output_artifacts": [
      {
        "output_artifact_id": "3f78e99c-5d35-4282-9e82-63c422f3af1b",
        "name": "tissue_qc:tiff_heatmap",
        "metadata": {},
        "state": "PENDING",
        "termination_reason": "SUCCEEDED",
        "output": "NONE",
        "error_code": "string",
        "error_message": "string",
        "download_url": "http://example.com"
      }
    ]
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
404	Not Found	Run not found	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

Status Code 200

Response List Run Items V1 Runs Run Id Items Get

Name	Type	Required	Restrictions	Description
Response List Run Items V1 Runs Run Id Items Get	[ItemResultReadResponse]	false	none	[Response schema for items in List Run Items endpoint]
» ItemResultReadResponse	ItemResultReadResponse	false	none	Response schema for items in List Run Items endpoint
»» item_id	string(uuid)	true	none	Item UUID generated by the Platform
»» external_id	string	true	none	The external_id of the item from the user payload
»» custom_metadata	any	true	none	The custom_metadata of the item that has been provided by the user on run creation.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» custom_metadata_checksum	any	false	none	The checksum of the custom_metadata field.Can be used in the PUT /runs/{run-id}/items/{external_id}/custom_metadatarequest to avoid unwanted override of the values in concurrent requests.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» queue_position_org	any	false	none	The position of the item in the organization’s queue.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» queue_position_platform	any	false	none	The position of the item in the platform’s queue.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» state	ItemState	true	none	none
»» output	ItemOutput	true	none	none
»» termination_reason	any	false	none	When the state is TERMINATED this will explain whySUCCEEDED -> Successful processing.USER_ERROR -> Failed because the provided input was invalid.SYSTEM_ERROR -> There was an error in the model or platform.SKIPPED -> Was cancelled

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	ItemTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» error_code	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» error_message	any	false	none	The error message in case the termination_reason is in USER_ERROR or SYSTEM_ERROR

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» terminated_at	any	false	none	Timestamp showing when the item reached a terminal state.

anyOf

Name	Type	Required	Restrictions	Description
»»» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» output_artifacts	[OutputArtifactResultReadResponse]	true	none	The list of the results generated by the application algorithm. The number of files and theirtypes depend on the particular application version, call /v1/versions/{version_id} to getthe details.
»»» OutputArtifactResultReadResponse	OutputArtifactResultReadResponse	false	none	none
»»»» output_artifact_id	string(uuid)	true	none	The Id of the artifact. Used internally
»»»» name	string	true	none	Name of the output from the output schema from the /v1/versions/{version_id} endpoint.
»»»» metadata	any	false	none	The metadata of the output artifact, provided by the application. Can only be None if the artifact itself was deleted.

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»» state	ArtifactState	true	none	none
»»»» termination_reason	any	false	none	The reason for termination when state is TERMINATED

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	ArtifactTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»» output	ArtifactOutput	true	none	none
»»»» error_code	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»» error_message	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»» download_url	any	false	none	The download URL to the output file. The URL is valid for 1 hour after the endpoint is called.A new URL is generated every time the endpoint is called.

anyOf

Name	Type	Required	Restrictions	Description
»»»»» anonymous	string(uri)	false	none	none

or

Name	Type	Required	Restrictions	Description
»»»»» anonymous	null	false	none	none

Enumerated Values

Property	Value
state	PENDING
state	PROCESSING
state	TERMINATED
output	NONE
output	FULL
anonymous	SUCCEEDED
anonymous	USER_ERROR
anonymous	SYSTEM_ERROR
anonymous	SKIPPED
state	PENDING
state	PROCESSING
state	TERMINATED
anonymous	SUCCEEDED
anonymous	USER_ERROR
anonymous	SYSTEM_ERROR
anonymous	SKIPPED
output	NONE
output	AVAILABLE
output	DELETED_BY_USER
output	DELETED_BY_SYSTEM

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

get_item_by_run_v1_runs__run_id__items__external_id__get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/runs/{run_id}/items/{external_id}", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/items/{external_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/runs/{run_id}/items/{external_id}

Get Item By Run

Retrieve details of a specific item (slide) by its external ID and the run ID.

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	The run id, returned by POST /runs/ endpoint
external_id	path	string	true	The external_id that was defined for the item by the customer that triggered the run.

Example responses

200 Response

{
  "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  "external_id": "slide_1",
  "custom_metadata": {},
  "custom_metadata_checksum": "f54fe109",
  "queue_position_org": 0,
  "queue_position_platform": 0,
  "state": "PENDING",
  "output": "NONE",
  "termination_reason": "SUCCEEDED",
  "error_code": "string",
  "error_message": "This item was not processed because the threshold of 3 items finishing in error state (user or system error) was reached before the item was processed.",
  "terminated_at": "2024-01-15T10:30:45.123Z",
  "output_artifacts": [
    {
      "output_artifact_id": "3f78e99c-5d35-4282-9e82-63c422f3af1b",
      "name": "tissue_qc:tiff_heatmap",
      "metadata": {},
      "state": "PENDING",
      "termination_reason": "SUCCEEDED",
      "output": "NONE",
      "error_code": "string",
      "error_message": "string",
      "download_url": "http://example.com"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	ItemResultReadResponse
403	Forbidden	Forbidden - You don’t have permission to see this item	None
404	Not Found	Not Found - Item with given ID does not exist	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

get_artifact_url_v1_runs__run_id__artifacts__artifact_id__file_get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/runs/{run_id}/artifacts/{artifact_id}/file", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/artifacts/{artifact_id}/file',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/runs/{run_id}/artifacts/{artifact_id}/file

Get Artifact Url

Download the artifact file with the specified artifact_id, belonging to the specified run. The artifact_is is returned by the GET /v1/runs/{run_id}/items endpoint as part of the item results, and can also be retrieved via GET /v1/runs/{run_id}/items/{external_id}.

The endpoint may return a redirect response with a presigned URL to download the artifact file from the storage bucket. The presigned URL is valid for a limited time, so it should be used immediately after receiving the response.

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /runs/ endpoint
artifact_id	path	string(uuid)	true	The artifact id to download

Example responses

200 Response

null

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
307	Temporary Redirect	Temporary Redirect - Redirect to the artifact file URL	None
403	Forbidden	Forbidden - You don’t have permission to download this artifact	None
404	Not Found	Not Found - Artifact not found for the specified run	None
410	Gone	Gone - Artifact has been deleted	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

delete_run_items_v1_runs__run_id__artifacts_delete

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.delete("/api/v1/runs/{run_id}/artifacts", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/artifacts',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /v1/runs/{run_id}/artifacts

Delete Run Items

This endpoint allows the caller to explicitly delete artifacts generated by a run. It can only be invoked when the run has reached a final state, i.e. PROCESSED, CANCELED_SYSTEM, or CANCELED_USER. Note that by default, all artifacts are automatically deleted 30 days after the run finishes, regardless of whether the caller explicitly requests such deletion.

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /runs/ endpoint

Example responses

200 Response

null

Responses

Status	Meaning	Description	Schema
200	OK	Run artifacts deleted	Inline
404	Not Found	Run not found	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

Response Schema

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

put_run_custom_metadata_v1_runs__run_id__custom_metadata_put

Code samples

import requests

headers = {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.put("/api/v1/runs/{run_id}/custom-metadata", headers=headers)

print(r.json())

const inputBody = '{
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/custom-metadata',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /v1/runs/{run_id}/custom-metadata

Put Run Custom Metadata

Update the custom metadata of a run with the specified run_id.

Optionally, a checksum may be provided along the custom metadata JSON. It can be used to verify if the custom metadata was updated since the last time it was accessed. If the checksum is provided, it must match the existing custom metadata in the system, ensuring that the current custom metadata value to be overwritten is acknowledged by the user. If no checksum is provided, submitted metadata directly overwrites the existing metadata, without any checks.

The latest custom metadata and checksum can be retrieved for the run via the GET /v1/runs/{run_id} endpoint.

Note on deadlines: Run deadlines must be set during run creation and cannot be modified afterward. Any deadline changes in custom metadata will be ignored by the system.

Body parameter

{
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109"
}

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	Run id, returned by POST /runs/ endpoint
body	body	CustomMetadataUpdateRequest	true	none

Example responses

200 Response

{
  "custom_metadata_checksum": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Custom metadata successfully updated	CustomMetadataUpdateResponse
403	Forbidden	Forbidden - You don’t have permission to update this run	None
404	Not Found	Run not found	None
412	Precondition Failed	Precondition Failed - Checksum mismatch, resource has been modified	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

put_item_custom_metadata_by_run_v1_runs__run_id__items__external_id__custom_metadata_put

Code samples

import requests

headers = {"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.put("/api/v1/runs/{run_id}/items/{external_id}/custom-metadata", headers=headers)

print(r.json())

const inputBody = '{
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/runs/{run_id}/items/{external_id}/custom-metadata',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /v1/runs/{run_id}/items/{external_id}/custom-metadata

Put Item Custom Metadata By Run

Update the custom metadata of the item with the specified external_id, belonging to the specified run.

Optionally, a checksum may be provided along the custom metadata JSON. It can be used to verify if the custom metadata was updated since the last time it was accessed. If the checksum is provided, it must match the existing custom metadata in the system, ensuring that the current custom metadata value to be overwritten is acknowledged by the user. If no checksum is provided, submitted metadata directly overwrites the existing metadata, without any checks.

The latest custom metadata and checksum can be retrieved for individual items via GET /v1/runs/{run_id}/items/{external_id}, and for all items of a run via GET /v1/runs/{run_id}/items.

Body parameter

{
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109"
}

Parameters

Name	In	Type	Required	Description
run_id	path	string(uuid)	true	The run id, returned by POST /runs/ endpoint
external_id	path	string	true	The external_id that was defined for the item by the customer that triggered the run.
body	body	CustomMetadataUpdateRequest	true	none

Example responses

200 Response

{
  "custom_metadata_checksum": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Custom metadata successfully updated	CustomMetadataUpdateResponse
403	Forbidden	Forbidden - You don’t have permission to update this item	None
404	Not Found	Item not found	None
412	Precondition Failed	Precondition Failed - Checksum mismatch	None
422	Unprocessable Entity	Validation Error	HTTPValidationError

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

get_me_v1_me_get

Code samples

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer {access-token}"}

r = requests.get("/api/v1/me", headers=headers)

print(r.json())

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/me',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /v1/me

Get current user

Retrieves your identity details, including name, email, and organization. This is useful for verifying that the request is being made under the correct user profile and organization context, as well as confirming that the expected environment variables are correctly set (in case you are using Python SDK)

Example responses

200 Response

{
  "user": {
    "id": "auth0|123456",
    "email": "user@domain.com",
    "email_verified": true,
    "name": "Jane Doe",
    "given_name": "Jane",
    "family_name": "Doe",
    "nickname": "jdoe",
    "picture": "https://example.com/jdoe.jpg",
    "updated_at": "2023-10-05T14:48:00.000Z"
  },
  "organization": {
    "id": "org_123456",
    "name": "aignx",
    "display_name": "Aignostics GmbH",
    "aignostics_bucket_hmac_access_key_id": "YOUR_HMAC_ACCESS_KEY_ID",
    "aignostics_bucket_hmac_secret_access_key": "YOUR/HMAC/SECRET_ACCESS_KEY",
    "aignostics_bucket_name": "aignostics-platform-bucket",
    "aignostics_bucket_protocol": "gs",
    "aignostics_logfire_token": "your-logfire-token",
    "aignostics_sentry_dsn": "https://2354s3#ewsha@o44.ingest.us.sentry.io/34345123432"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	MeReadResponse

To perform this operation, you must be authenticated by means of one of the following methods: OAuth2AuthorizationCodeBearer

Schemas

ApplicationReadResponse

{
  "application_id": "he-tme",
  "name": "Atlas H&E-TME",
  "regulatory_classes": [
    "RUO"
  ],
  "description": "The Atlas H&E TME is an AI application designed to examine FFPE (formalin-fixed, paraffin-embedded) tissues stained with H&E (hematoxylin and eosin), delivering comprehensive insights into the tumor microenvironment.",
  "versions": [
    {
      "number": "1.0.0",
      "released_at": "2025-09-15T10:30:45.123Z"
    }
  ]
}

ApplicationReadResponse

Properties

Name	Type	Required	Restrictions	Description
application_id	string	true	none	Application ID
name	string	true	none	Application display name
regulatory_classes	[string]	true	none	Regulatory classes, to which the applications comply with. Possible values include: RUO, IVDR, FDA.
description	string	true	none	Describing what the application can do
versions	[ApplicationVersion]	true	none	All version numbers available to the user

ApplicationReadShortResponse

{
  "application_id": "he-tme",
  "name": "Atlas H&E-TME",
  "regulatory_classes": [
    "RUO"
  ],
  "description": "The Atlas H&E TME is an AI application designed to examine FFPE (formalin-fixed, paraffin-embedded) tissues stained with H&E (hematoxylin and eosin), delivering comprehensive insights into the tumor microenvironment.",
  "latest_version": {
    "number": "1.0.0",
    "released_at": "2025-09-15T10:30:45.123Z"
  }
}

ApplicationReadShortResponse

Properties

Name	Type	Required	Restrictions	Description
application_id	string	true	none	Application ID
name	string	true	none	Application display name
regulatory_classes	[string]	true	none	Regulatory classes, to which the applications comply with. Possible values include: RUO, IVDR, FDA.
description	string	true	none	Describing what the application can do
latest_version	any	false	none	The version with highest version number available to the user

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	ApplicationVersion	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

ApplicationVersion

{
  "number": "1.0.0",
  "released_at": "2025-09-15T10:30:45.123Z"
}

ApplicationVersion

Properties

Name	Type	Required	Restrictions	Description
number	string	true	none	The number of the latest version
released_at	string(date-time)	true	none	The timestamp for when the application version was made available in the Platform

ArtifactOutput

"NONE"

ArtifactOutput

Properties

Name	Type	Required	Restrictions	Description
ArtifactOutput	string	false	none	none

Enumerated Values

Property	Value
ArtifactOutput	NONE
ArtifactOutput	AVAILABLE
ArtifactOutput	DELETED_BY_USER
ArtifactOutput	DELETED_BY_SYSTEM

ArtifactState

"PENDING"

ArtifactState

Properties

Name	Type	Required	Restrictions	Description
ArtifactState	string	false	none	none

Enumerated Values

Property	Value
ArtifactState	PENDING
ArtifactState	PROCESSING
ArtifactState	TERMINATED

ArtifactTerminationReason

"SUCCEEDED"

ArtifactTerminationReason

Properties

Name	Type	Required	Restrictions	Description
ArtifactTerminationReason	string	false	none	none

Enumerated Values

Property	Value
ArtifactTerminationReason	SUCCEEDED
ArtifactTerminationReason	USER_ERROR
ArtifactTerminationReason	SYSTEM_ERROR
ArtifactTerminationReason	SKIPPED

CustomMetadataUpdateRequest

{
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109"
}

CustomMetadataUpdateRequest

Properties

Name	Type	Required	Restrictions	Description
custom_metadata	any	false	none	JSON metadata that should be set for the run

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
custom_metadata_checksum	any	false	none	Optional field to verify that the latest custom metadata was known. If set to the checksum retrieved via the /runs endpoint, it must match the checksum of the current value in the database.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

CustomMetadataUpdateResponse

{
  "custom_metadata_checksum": "string"
}

CustomMetadataUpdateResponse

Properties

Name	Type	Required	Restrictions	Description
custom_metadata_checksum	any	true	read-only	The checksum of the updated custom metadata. If the custom_metadata is None,the checksum also None.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

HTTPValidationError

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

HTTPValidationError

Properties

Name	Type	Required	Restrictions	Description
detail	[ValidationError]	false	none	none

InputArtifact

{
  "name": "string",
  "mime_type": "image/tiff",
  "metadata_schema": {}
}

InputArtifact

Properties

Name	Type	Required	Restrictions	Description
name	string	true	none	none
mime_type	string	true	none	none
metadata_schema	object	true	none	none

InputArtifactCreationRequest

{
  "name": "input_slide",
  "download_url": "https://example.com/case-no-1-slide.tiff",
  "metadata": {
    "checksum_base64_crc32c": "752f9554",
    "height": 2000,
    "height_mpp": 0.5,
    "width": 10000,
    "width_mpp": 0.5
  }
}

InputArtifactCreationRequest

Properties

Name	Type	Required	Restrictions	Description
name	string	true	none	Type of artifact. For Atlas H&E-TME, use “input_slide”
download_url	string(uri)	true	none	Signed URL to the input artifact file. The URL should be valid for at least 6 days from the payload submission time.
metadata	object	true	none	The metadata of the artifact, required by the application version. The JSON schema of the metadata can be requested by /v1/versions/{application_version_id}. The schema is located in input_artifacts.[].metadata_schema

ItemCreationRequest

{
  "external_id": "slide_1",
  "custom_metadata": {
    "case": "abc"
  },
  "input_artifacts": [
    {
      "download_url": "https://example-bucket.s3.amazonaws.com/slide1.tiff",
      "metadata": {
        "checksum_base64_crc32c": "64RKKA==",
        "height_px": 87761,
        "media-type": "image/tiff",
        "resolution_mpp": 0.2628238,
        "specimen": {
          "disease": "LUNG_CANCER",
          "tissue": "LUNG"
        },
        "staining_method": "H&E",
        "width_px": 136223
      },
      "name": "input_slide"
    }
  ]
}

ItemCreationRequest

Properties

Name	Type	Required	Restrictions	Description
external_id	string	true	none	Unique identifier for this item within the run. Used for referencing items. Must be unique across all items in the same run
custom_metadata	any	false	none	Optional JSON custom_metadata to store additional information alongside an item.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
input_artifacts	[InputArtifactCreationRequest]	true	none	List of input artifacts for this item. For Atlas H&E-TME, typically contains one artifact (the slide image)

ItemOutput

"NONE"

ItemOutput

Properties

Name	Type	Required	Restrictions	Description
ItemOutput	string	false	none	none

Enumerated Values

Property	Value
ItemOutput	NONE
ItemOutput	FULL

ItemResultReadResponse

{
  "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  "external_id": "slide_1",
  "custom_metadata": {},
  "custom_metadata_checksum": "f54fe109",
  "queue_position_org": 0,
  "queue_position_platform": 0,
  "state": "PENDING",
  "output": "NONE",
  "termination_reason": "SUCCEEDED",
  "error_code": "string",
  "error_message": "This item was not processed because the threshold of 3 items finishing in error state (user or system error) was reached before the item was processed.",
  "terminated_at": "2024-01-15T10:30:45.123Z",
  "output_artifacts": [
    {
      "output_artifact_id": "3f78e99c-5d35-4282-9e82-63c422f3af1b",
      "name": "tissue_qc:tiff_heatmap",
      "metadata": {},
      "state": "PENDING",
      "termination_reason": "SUCCEEDED",
      "output": "NONE",
      "error_code": "string",
      "error_message": "string",
      "download_url": "http://example.com"
    }
  ]
}

ItemResultReadResponse

Properties

Name	Type	Required	Restrictions	Description
item_id	string(uuid)	true	none	Item UUID generated by the Platform
external_id	string	true	none	The external_id of the item from the user payload
custom_metadata	any	true	none	The custom_metadata of the item that has been provided by the user on run creation.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
custom_metadata_checksum	any	false	none	The checksum of the custom_metadata field.Can be used in the PUT /runs/{run-id}/items/{external_id}/custom_metadatarequest to avoid unwanted override of the values in concurrent requests.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
queue_position_org	any	false	none	The position of the item in the organization’s queue.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
queue_position_platform	any	false	none	The position of the item in the platform’s queue.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
state	ItemState	true	none	The item moves from PENDING to PROCESSING to TERMINATED state.When terminated, consult the termination_reason property to see whether it was successful.
output	ItemOutput	true	none	The output status of the item (NONE, FULL)
termination_reason	any	false	none	When the state is TERMINATED this will explain whySUCCEEDED -> Successful processing.USER_ERROR -> Failed because the provided input was invalid.SYSTEM_ERROR -> There was an error in the model or platform.SKIPPED -> Was cancelled

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	ItemTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
error_code	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
error_message	any	false	none	The error message in case the termination_reason is in USER_ERROR or SYSTEM_ERROR

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
terminated_at	any	false	none	Timestamp showing when the item reached a terminal state.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
output_artifacts	[OutputArtifactResultReadResponse]	true	none	The list of the results generated by the application algorithm. The number of files and theirtypes depend on the particular application version, call /v1/versions/{version_id} to getthe details.

ItemState

"PENDING"

ItemState

Properties

Name	Type	Required	Restrictions	Description
ItemState	string	false	none	none

Enumerated Values

Property	Value
ItemState	PENDING
ItemState	PROCESSING
ItemState	TERMINATED

ItemTerminationReason

"SUCCEEDED"

ItemTerminationReason

Properties

Name	Type	Required	Restrictions	Description
ItemTerminationReason	string	false	none	none

Enumerated Values

Property	Value
ItemTerminationReason	SUCCEEDED
ItemTerminationReason	USER_ERROR
ItemTerminationReason	SYSTEM_ERROR
ItemTerminationReason	SKIPPED

MeReadResponse

{
  "user": {
    "id": "auth0|123456",
    "email": "user@domain.com",
    "email_verified": true,
    "name": "Jane Doe",
    "given_name": "Jane",
    "family_name": "Doe",
    "nickname": "jdoe",
    "picture": "https://example.com/jdoe.jpg",
    "updated_at": "2023-10-05T14:48:00.000Z"
  },
  "organization": {
    "id": "org_123456",
    "name": "aignx",
    "display_name": "Aignostics GmbH",
    "aignostics_bucket_hmac_access_key_id": "YOUR_HMAC_ACCESS_KEY_ID",
    "aignostics_bucket_hmac_secret_access_key": "YOUR/HMAC/SECRET_ACCESS_KEY",
    "aignostics_bucket_name": "aignostics-platform-bucket",
    "aignostics_bucket_protocol": "gs",
    "aignostics_logfire_token": "your-logfire-token",
    "aignostics_sentry_dsn": "https://2354s3#ewsha@o44.ingest.us.sentry.io/34345123432"
  }
}

MeReadResponse

Properties

Name	Type	Required	Restrictions	Description
user	UserReadResponse	true	none	Part of response schema for User object in Get current user endpoint.This model corresponds to the response schema returned fromAuth0 GET /v2/users/{id} endpoint.For details, see:https://auth0.com/docs/api/management/v2/users/get-users-by-id
organization	OrganizationReadResponse	true	none	Part of response schema for Organization object in Get current user endpoint.This model corresponds to the response schema returned fromAuth0 GET /v2/organizations/{id} endpoint, flattens out the metadata outand doesn’t return branding or token_quota objects.For details, see:https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id#### Configuration for integrating with Aignostics Platform services.The Aignostics Platform API requires signed URLs for input artifacts (slide images). To simplify this process,Aignostics provides a dedicated storage bucket. The HMAC credentials below grant read and writeaccess to this bucket, allowing you to upload files and generate the signed URLs needed for API calls.Additionally, logging and error reporting tokens enable Aignostics to provide better support and monitorsystem performance for your integration.

OrganizationReadResponse

{
  "id": "org_123456",
  "name": "aignx",
  "display_name": "Aignostics GmbH",
  "aignostics_bucket_hmac_access_key_id": "YOUR_HMAC_ACCESS_KEY_ID",
  "aignostics_bucket_hmac_secret_access_key": "YOUR/HMAC/SECRET_ACCESS_KEY",
  "aignostics_bucket_name": "aignostics-platform-bucket",
  "aignostics_bucket_protocol": "gs",
  "aignostics_logfire_token": "your-logfire-token",
  "aignostics_sentry_dsn": "https://2354s3#ewsha@o44.ingest.us.sentry.io/34345123432"
}

OrganizationReadResponse

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	Unique organization identifier
name	any	false	none	Organization name (E.g. “aignx”)

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
display_name	any	false	none	Public organization name (E.g. “Aignostics GmbH”)

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
aignostics_bucket_hmac_access_key_id	string	true	none	HMAC access key ID for the Aignostics-provided storage bucket. Used to authenticate requests for uploading files and generating signed URLs
aignostics_bucket_hmac_secret_access_key	string	true	none	HMAC secret access key paired with the access key ID. Keep this credential secure.
aignostics_bucket_name	string	true	none	Name of the bucket provided by Aignostics for storing input artifacts (slide images)
aignostics_bucket_protocol	string	true	none	Protocol to use for bucket access. Defines the URL scheme for connecting to the storage service
aignostics_logfire_token	string	true	none	Authentication token for Logfire observability service. Enables sending application logs and performance metrics to Aignostics for monitoring and support
aignostics_sentry_dsn	string	true	none	Data Source Name (DSN) for Sentry error tracking service. Allows automatic reporting of errors and exceptions to Aignostics support team

OutputArtifact

{
  "name": "string",
  "mime_type": "application/vnd.apache.parquet",
  "metadata_schema": {},
  "scope": "ITEM",
  "visibility": "INTERNAL"
}

OutputArtifact

Properties

Name	Type	Required	Restrictions	Description
name	string	true	none	none
mime_type	string	true	none	none
metadata_schema	object	true	none	none
scope	OutputArtifactScope	true	none	none
visibility	OutputArtifactVisibility	true	none	none

OutputArtifactResultReadResponse

{
  "output_artifact_id": "3f78e99c-5d35-4282-9e82-63c422f3af1b",
  "name": "tissue_qc:tiff_heatmap",
  "metadata": {},
  "state": "PENDING",
  "termination_reason": "SUCCEEDED",
  "output": "NONE",
  "error_code": "string",
  "error_message": "string",
  "download_url": "http://example.com"
}

OutputArtifactResultReadResponse

Properties

Name	Type	Required	Restrictions	Description
output_artifact_id	string(uuid)	true	none	The Id of the artifact. Used internally
name	string	true	none	Name of the output from the output schema from the /v1/versions/{version_id} endpoint.
metadata	any	false	none	The metadata of the output artifact, provided by the application. Can only be None if the artifact itself was deleted.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
state	ArtifactState	true	none	The current state of the artifact (PENDING, PROCESSING, TERMINATED)
termination_reason	any	false	none	The reason for termination when state is TERMINATED

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	ArtifactTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
output	ArtifactOutput	true	none	The output status of the artifact (NONE, FULL)
error_code	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
error_message	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
download_url	any	false	none	The download URL to the output file. The URL is valid for 1 hour after the endpoint is called.A new URL is generated every time the endpoint is called.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(uri)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

OutputArtifactScope

"ITEM"

OutputArtifactScope

Properties

Name	Type	Required	Restrictions	Description
OutputArtifactScope	string	false	none	none

Enumerated Values

Property	Value
OutputArtifactScope	ITEM
OutputArtifactScope	GLOBAL

OutputArtifactVisibility

"INTERNAL"

OutputArtifactVisibility

Properties

Name	Type	Required	Restrictions	Description
OutputArtifactVisibility	string	false	none	none

Enumerated Values

Property	Value
OutputArtifactVisibility	INTERNAL
OutputArtifactVisibility	EXTERNAL

RunCreationRequest

{
  "application_id": "he-tme",
  "version_number": "1.0.0-beta1",
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "scheduling": {
    "deadline": "2026-03-05T23:59:59Z",
    "due_date": "2026-03-04T23:59:59Z"
  },
  "items": [
    {
      "external_id": "slide_1",
      "input_artifacts": [
        {
          "download_url": "https://example-bucket.s3.amazonaws.com/slide1.tiff?signature=...",
          "metadata": {
            "checksum_base64_crc32c": "64RKKA==",
            "height_px": 87761,
            "media-type": "image/tiff",
            "resolution_mpp": 0.2628238,
            "specimen": {
              "disease": "LUNG_CANCER",
              "tissue": "LUNG"
            },
            "staining_method": "H&E",
            "width_px": 136223
          },
          "name": "input_slide"
        }
      ]
    }
  ]
}

RunCreationRequest

Properties

Name	Type	Required	Restrictions	Description
application_id	string	true	none	Unique ID for the application to use for processing
version_number	any	false	none	Semantic version of the application to use for processing. If not provided, the latest available version will be used

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
custom_metadata	any	false	none	Optional JSON metadata to store additional information alongside the run

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
scheduling	any	false	none	Optional scheduling constraints for this run.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	SchedulingRequest	false	none	Scheduling constraints for a run.

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
items	[ItemCreationRequest]	true	none	List of items (slides) to process. Each item represents a whole slide image (WSI) with its associated metadata and artifacts

RunCreationResponse

{
  "run_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

RunCreationResponse

Properties

Name	Type	Required	Restrictions	Description
run_id	string(uuid)	true	none	none

RunItemStatistics

{
  "item_count": 0,
  "item_pending_count": 0,
  "item_processing_count": 0,
  "item_user_error_count": 0,
  "item_system_error_count": 0,
  "item_skipped_count": 0,
  "item_succeeded_count": 0
}

RunItemStatistics

Properties

Name	Type	Required	Restrictions	Description
item_count	integer	true	none	Total number of the items in the run
item_pending_count	integer	true	none	The number of items in PENDING state
item_processing_count	integer	true	none	The number of items in PROCESSING state
item_user_error_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is USER_ERROR
item_system_error_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SYSTEM_ERROR
item_skipped_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SKIPPED
item_succeeded_count	integer	true	none	The number of items in TERMINATED state, and the item termination reason is SUCCEEDED

RunOutput

"NONE"

RunOutput

Properties

Name	Type	Required	Restrictions	Description
RunOutput	string	false	none	none

Enumerated Values

Property	Value
RunOutput	NONE
RunOutput	PARTIAL
RunOutput	FULL

RunReadResponse

{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "application_id": "he-tme",
  "version_number": "0.4.4",
  "state": "PENDING",
  "output": "NONE",
  "termination_reason": "ALL_ITEMS_PROCESSED",
  "error_code": "SCHEDULER.ITEMS_WITH_ERROR_THRESHOLD_REACHED",
  "error_message": "Run canceled given errors on more than 10 items.",
  "statistics": {
    "item_count": 0,
    "item_pending_count": 0,
    "item_processing_count": 0,
    "item_user_error_count": 0,
    "item_system_error_count": 0,
    "item_skipped_count": 0,
    "item_succeeded_count": 0
  },
  "custom_metadata": {
    "department": "D1",
    "study": "abc-1"
  },
  "custom_metadata_checksum": "f54fe109",
  "submitted_at": "2019-08-24T14:15:22Z",
  "submitted_by": "auth0|123456",
  "terminated_at": "2024-01-15T10:30:45.123Z",
  "num_preceding_items_org": 0,
  "num_preceding_items_platform": 0,
  "scheduling": {
    "due_date": "2019-08-24T14:15:22Z",
    "deadline": "2019-08-24T14:15:22Z"
  }
}

RunReadResponse

Properties

Name	Type	Required	Restrictions	Description
run_id	string(uuid)	true	none	UUID of the application
application_id	string	true	none	Application id
version_number	string	true	none	Application version number
state	RunState	true	none	When the run request is received by the Platform, the state of it is set toPENDING. The state changes to PROCESSING when at least one item is being processed. After PROCESSING, thestate of the run can switch back to PENDING if there are no processing items, or to TERMINATED when the runfinished processing.
output	RunOutput	true	none	The status of the output of the run. When 0 items are successfully processed the output isNONE, after one item is successfully processed, the value is set to PARTIAL. When all items of the run aresuccessfully processed, the output is set to FULL.
termination_reason	any	true	none	The termination reason of the run. When the run is not in TERMINATED state, the termination_reason is null. If all items of of the run are processed (successfully or with an error), then termination_reason is set to ALL_ITEMS_PROCESSED. If the run is cancelled by the user, the value is set to CANCELED_BY_USER. If the run reaches the threshold of number of failed items, the Platform cancels the run and sets the termination_reason to CANCELED_BY_SYSTEM.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	RunTerminationReason	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
error_code	any	true	none	When the termination_reason is set to CANCELED_BY_SYSTEM, the error_code is set to define the structured description of the error.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
error_message	any	true	none	When the termination_reason is set to CANCELED_BY_SYSTEM, the error_message is set to provide more insights to the error cause.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
statistics	RunItemStatistics	true	none	Aggregated statistics of the run execution
custom_metadata	any	false	none	Optional JSON metadata that was stored in alongside the run by the user

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
custom_metadata_checksum	any	false	none	The checksum of the custom_metadata field. Can be used in the PUT /runs/{run-id}/custom_metadatarequest to avoid unwanted override of the values in concurrent requests.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
submitted_at	string(date-time)	true	none	Timestamp showing when the run was triggered
submitted_by	string	true	none	Id of the user who triggered the run
terminated_at	any	false	none	Timestamp showing when the run reached a terminal state.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
num_preceding_items_org	any	false	none	How many Items from other Runs in the same Organization are due to begin processing before this Run’s next Item does.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
num_preceding_items_platform	any	false	none	How many Items from other Runs are due to begin processing before this Run’s next Item does.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	integer	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
scheduling	any	false	none	Scheduling constraints set for this run.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	SchedulingResponse	false	none	Scheduling fields returned in run responses.

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

RunState

"PENDING"

RunState

Properties

Name	Type	Required	Restrictions	Description
RunState	string	false	none	none

Enumerated Values

Property	Value
RunState	PENDING
RunState	PROCESSING
RunState	TERMINATED

RunTerminationReason

"ALL_ITEMS_PROCESSED"

RunTerminationReason

Properties

Name	Type	Required	Restrictions	Description
RunTerminationReason	string	false	none	none

Enumerated Values

Property	Value
RunTerminationReason	ALL_ITEMS_PROCESSED
RunTerminationReason	CANCELED_BY_SYSTEM
RunTerminationReason	CANCELED_BY_USER

SchedulingRequest

{
  "due_date": "2026-03-04T23:59:59Z",
  "deadline": "2026-03-05T23:59:59Z"
}

SchedulingRequest

Properties

Name	Type	Required	Restrictions	Description
due_date	any	false	none	Requested completion time. Items are prioritized to meet this target.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
deadline	any	false	none	Hard deadline. The run will be cancelled if not completed by this time.

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

SchedulingResponse

{
  "due_date": "2019-08-24T14:15:22Z",
  "deadline": "2019-08-24T14:15:22Z"
}

SchedulingResponse

Properties

Name	Type	Required	Restrictions	Description
due_date	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
deadline	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

UserReadResponse

{
  "id": "auth0|123456",
  "email": "user@domain.com",
  "email_verified": true,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "nickname": "jdoe",
  "picture": "https://example.com/jdoe.jpg",
  "updated_at": "2023-10-05T14:48:00.000Z"
}

UserReadResponse

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	Unique user identifier
email	any	false	none	User email

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
email_verified	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	boolean	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
name	any	false	none	First and last name of the user

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
given_name	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
family_name	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
nickname	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
picture	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

continued

Name	Type	Required	Restrictions	Description
updated_at	any	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string(date-time)	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	null	false	none	none

ValidationError

{
  "loc": [
    "string"
  ],
  "msg": "string",
  "type": "string",
  "input": null,
  "ctx": {}
}

ValidationError

Properties

Name	Type	Required	Restrictions	Description
loc	[anyOf]	true	none	none

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

or

Name	Type	Required	Restrictions	Description
» anonymous	integer	false	none	none

continued

Name	Type	Required	Restrictions	Description
msg	string	true	none	none
type	string	true	none	none
input	any	false	none	none
ctx	object	false	none	none

VersionReadResponse

{
  "version_number": "string",
  "changelog": "string",
  "input_artifacts": [
    {
      "name": "string",
      "mime_type": "image/tiff",
      "metadata_schema": {}
    }
  ],
  "output_artifacts": [
    {
      "name": "string",
      "mime_type": "application/vnd.apache.parquet",
      "metadata_schema": {},
      "scope": "ITEM",
      "visibility": "INTERNAL"
    }
  ],
  "released_at": "2019-08-24T14:15:22Z"
}

VersionReadResponse

Properties

Name	Type	Required	Restrictions	Description
version_number	string	true	none	Semantic version of the application
changelog	string	true	none	Description of the changes relative to the previous version
input_artifacts	[InputArtifact]	true	none	List of the input fields, provided by the User
output_artifacts	[OutputArtifact]	true	none	List of the output fields, generated by the application
released_at	string(date-time)	true	none	The timestamp when the application version was registered