Skip to main content

Shared schema

Several request fields and response fragments appear in more than one endpoint. They are documented once on this page and referenced from each endpoint walkthrough.

Authentication header​

Every endpoint except /login requires a bearer token in the Authorization header:

Authorization: Bearer <access_token>

Obtain the token from the Login endpoint and re-issue it before expires_in_minutes elapses. If a clinical endpoint returns an authentication or authorization error, treat it as token expiration and retry after a fresh login.

FHIR response envelope​

Every clinical endpoint returns a FHIR DiagnosticReport envelope at the top of the response:

{
  "resourceType": "DiagnosticReport",
  "identifier": {
    "use": "official",
    "value": "f426f15d-fcea-4bd0-942e-7528bf163c5d"
  },
  "status": "preliminary",
  "issued": "2026-02-13T14:58:27.466367",
  "analysisDuration": 1.11359
}
  • resourceType always "DiagnosticReport" (FHIR-compliant).
  • identifier.value UUID for this report. Persist it on your side for audit and traceability.
  • status FHIR status; "preliminary" indicates an AI-generated result that has not been validated by a clinician.
  • issued ISO-8601 timestamp at which the report was generated.
  • analysisDuration number of seconds the AI took to produce the report.

/diagnosis-support additionally carries category and code blocks describing the type of report (Diagnostic Imaging, LOINC 100063-7 "Primary skin concern"); they are static for that endpoint and can be ignored in most integrations.

Image attachment (contentAttachment)​

Every endpoint that accepts an image carries it inside a contentAttachment object:

"contentAttachment": {
  "data": "<base64_encoded_image_data>",
  "title": "Lesion close-up",
  "contentType": "image/jpeg"
}
  • data (required) image bytes, Base64-encoded.
  • title (optional) free-text label preserved in the response, useful for correlating images with anatomy or capture context.
  • contentType (optional) MIME type. Defaults to image/png; set to image/jpeg for JPEG images.

Image quality assessment: mediaValidity​

Every endpoint that accepts an image returns a mediaValidity block describing whether the image is suitable for AI analysis.

"mediaValidity": {
  "quality": {
    "acceptable": true,
    "score": 93,
    "interpretation": "Excellent"
  },
  "domain": {
    "isDermatological": true,
    "additionalData": {
      "aiConfidence": {
        "code": {
          "coding": [
            {
              "systemDisplay": "Legit.Health",
              "code": "aiConfidence",
              "text": "AI model confidence in the image being dermatological"
            }
          ]
        },
        "value": 99.99999296
      }
    }
  },
  "modality": {
    "value": "Clinical",
    "additionalData": {
      "aiConfidenceClinical": { "value": 99.99998808 },
      "aiConfidenceDermoscopic": { "value": 0.0 }
    }
  },
  "isValid": true
}
  • quality.acceptable boolean. Whether the image meets the minimum quality threshold required for clinical use.
  • quality.score integer 0–100. Image quality score, where 0 is unusable and 100 is perfect.
  • quality.interpretation categorical bucket for quality.score. How to interpret the score: Bad, Poor, Fair, Good, Excellent.
  • domain.isDermatological boolean. Whether the image contains skin (i.e. is in the dermatological domain).
  • domain.additionalData.aiConfidence.value float 0–100. AI confidence (in percent) that the image is dermatological.
  • modality.value image classification: None, Clinical, or Dermoscopic.
  • modality.additionalData.aiConfidenceClinical.value / aiConfidenceDermoscopic.value AI confidence (in percent) for each modality classification.
  • isValid boolean. true only when the image is dermatological AND of acceptable quality. Use this single flag as your gate to consume the AI output for clinical purposes.
Use isValid as your integration gate

If mediaValidity.isValid is false, downstream fields (such as conclusion[] or patientEvolution) may still be present but should not be acted upon clinically. Display the quality information to the operator and prompt them to retake the image.

Body site (bodySite)​

bodySite accepts any code returned by GET /body-sites. Do not hardcode the list of body sites the catalogue evolves as new sites are added. See the Body sites helper for usage.

Known condition (knownCondition)​

"knownCondition": {
  "conclusion": { "text": "<plain-text condition>" }
}
  • conclusion.text (required) plain-text name of the condition (e.g. the conclusion text returned by /diagnosis-support, or a clinician-supplied label). The API resolves the text internally to the relevant ICD-11 codes.

Scoring system (scoringSystem and questionnaireResponse)​

"scoringSystem": {
  "<scoring_system_code>": {
    "questionnaireResponse": {
      "item": { "<item_code>": "<answer_value>" }
    }
  }
}
  • scoringSystem.<code> (required) exactly one scoring-system code returned by GET /questionnaires.
  • scoringSystem.<code>.questionnaireResponse.item clinical inputs the AI cannot infer from the image (patient demographics, patient-reported symptoms, region body-surface-area percentage). The required item codes and accepted value ranges depend on the chosen scoring system and are returned by GET /questionnaires?code=<scoring_system_code>.

Do not hardcode either the scoring-system list or the item schema call the helper endpoints at integration time so new scorers and items added in the future do not break the integration. Sending a request without the required items returns a 422 validation error. See the Questionnaires helper for usage.