Skip to main content

Codes

Each study can have a Codes object — a dictionary that maps internal field codes to human-readable display labels. This is used to provide column labels and display names for study-specific fields within the Patholytix platform.

What Codes are​

Codes are stored as a flat key-value map where each key is an internal field code and the value is the display name shown to users.

{
  "codes": {
    "GRP": "Group",
    "SEX": "Sex",
    "DOSE": "Dose Level",
    "ROUTE": "Route of Administration"
  }
}

There is exactly one Codes object per study. Attempting to create a second one returns 409 Conflict.

Endpoints​

Get codes​

curl "https://api.dev2.patholytix.com/api/v1/studies/{studyId}/codes" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns the current Codes object for the study, or 404 Not Found if none has been created yet.

Required scope: Study:Read

Create codes​

curl -X POST "https://api.dev2.patholytix.com/api/v1/studies/{studyId}/codes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "codes": {
      "GRP": "Group",
      "SEX": "Sex",
      "DOSE": "Dose Level"
    }
  }'

Creates the Codes object for the study. Returns 409 Conflict if Codes already exist — use PUT to update.

Required scope: Study:Write

Replace codes​

curl -X PUT "https://api.dev2.patholytix.com/api/v1/studies/{studyId}/codes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "codes": {
      "GRP": "Group",
      "SEX": "Sex",
      "DOSE": "Dose Level",
      "ROUTE": "Route of Administration"
    }
  }'

Replaces the entire Codes object. The PUT body is the complete new state — any keys omitted are removed.

Required scope: Study:Write

Response format​

All three endpoints return the Codes resource:

{
  "codeId": "6a4c2b1e9fd0e300010ab7f2",
  "studyId": "5cd97ae75fdbf7000143cb30",
  "codes": {
    "GRP": "Group",
    "SEX": "Sex",
    "DOSE": "Dose Level",
    "ROUTE": "Route of Administration"
  },
  "createdDate": "2025-03-01T10:00:00Z",
  "updatedDate": "2025-03-15T14:30:00Z"
}
FieldTypeDescription
codeIdstringSystem-assigned identifier for the Codes object
studyIdstringThe study this Codes object belongs to
codesobjectKey-value map of field codes to display labels
createdDatestring (ISO 8601)Timestamp of initial creation
updatedDatestring (ISO 8601)Timestamp of last replacement

Codes in Subject and Organ responses​

When you retrieve a Subject, Organ, or Study, the response includes a codes field. This is a filtered view of the study's Codes dictionary — only entries whose keys match keys present in that entity's attributes map are included.

For example, if the study's Codes dictionary is:

{
  "MISPEC": "Organ",
  "SUBJID": "Subject Id",
  "DOSE": "Dose Level",
  "SEX": "Sex"
}

And a subject has attributes: { "DOSE": "10mg", "SEX": "M" }, its response codes will be:

{
  "codes": {
    "DOSE": "Dose Level",
    "SEX": "Sex"
  }
}

Keys present in the study's Codes dictionary but absent from the entity's attributes are omitted from the entity response. This makes the codes field a ready-made column-label mapping scoped to the attributes actually present on that entity.

Status codes​

StatusMeaning
200 OKGET or PUT succeeded
201 CreatedPOST succeeded — Codes object created
404 Not FoundNo Codes object exists for this study (GET only)
409 ConflictCodes already exist for this study (POST only) — use PUT to update

Next steps​