Upload custom code system

POST/construe/upload

Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan. Returns 202 immediately; embedding generation runs asynchronously. Poll GET /construe/codes/systems/{codesystem}?version={version} to check when status transitions from "processing" to "ready" or "failed".

RequiresBearerauthentication

Body parameters

namestringrequired

Name of the code system. Names are case-insensitive and stored uppercase. Builtin system names (e.g. ICD-10-CM, SNOMED_CT_US_LITE, LOINC, CPT, etc.) are reserved and cannot be used for custom uploads; attempts return HTTP 403 Forbidden.

versionstringrequired

Version of the code system

revisionnumberoptional

Optional revision number

formatstringrequired

Upload format

csvjson

filestring (byte)optional

The file contents as a base64-encoded string. For CSV format, this is the CSV file contents. For JSON format, this is a base64-encoded JSON array; prefer using 'codes' instead.

code_colstringoptional

Column name containing codes (required for CSV format)

desc_colstringoptional

Column name containing descriptions (required for CSV format)

defn_colstringoptional

Optional column name containing long definitions (for CSV format)

codesobject[]optional

The codes to upload as a JSON array (JSON format only). This is the preferred way to upload JSON codes, as it avoids unnecessary base64 encoding. If both 'codes' and 'file' are provided, 'codes' takes precedence.

codestringrequired

The code identifier

descriptionstringrequired

Short description of the code

definitionstringoptional

Extended definition of the code (if available)

replacebooleanoptionaldefault false

If true, replaces an existing code system with the same name and version. Builtin systems cannot be replaced; attempts to do so return HTTP 403 Forbidden. When false (default), uploading a duplicate returns 409 Conflict.

Returns

Upload accepted for asynchronous processing

Response fields

statusstringoptional

namestringoptional

versionstringoptional

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/construe/upload" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CUSTOM_CODES",
  "version": "1.0",
  "format": "json",
  "codes": [
    {
      "code": "X001",
      "description": "Example custom code 1"
    },
    {
      "code": "X002",
      "description": "Example custom code 2"
    }
  ]
}'

202 AcceptedExample Response

{
  "status": "processing",
  "name": "CUSTOM_CODES",
  "version": "1.0"
}