Add a retained version to a custom FHIR profile

POST/fhir/profiles/{id}/versions

Adds an immutable StructureDefinition version to a custom profile. If the profile does not exist, it is created from the submitted version. The StructureDefinition must include a non-empty version; its canonical URL and resource type must match the profile when one already exists. If it includes an id, that id must match the path parameter; if it omits id, the path parameter is used. Profiles created through this endpoint are grouped under custom. Posting the profile's current StructureDefinition unchanged retains it as a version. Version strings may contain letters, numbers, and the punctuation characters ., _, ~, +, and -; they cannot be exactly . or ... Each profile can retain up to 250 versions; delete old versions before adding more.

RequiresBearerauthentication

Path parameters

idstringrequired

The lowercase StructureDefinition id of the custom profile.

Returns

Profile version successfully created

Response fields

idstringrequired

The lowercase StructureDefinition id, used as the profile's lookup key.

sourcestringrequired

The profile's origin. Profile management responses currently return custom (uploaded) profiles, so this is always "custom" today.

custombuiltin

resource_typestringrequired

The FHIR resource type from the StructureDefinition.

urlstringrequired

The canonical URL from the StructureDefinition.

versionstringrequired

The version from the StructureDefinition.version field.

statusstringoptional

The publication status from StructureDefinition.status. Expected FHIR values include draft, active, retired, and unknown; the server preserves authored strings.

datestringoptional

The authored publication date from StructureDefinition.date, when present. This is a FHIR dateTime string and may be less precise than a full timestamp.

canonicalstringrequired

The canonical profile reference, including the version pin when present.

fhir_versionstringrequired

The base FHIR version the StructureDefinition targets.

implementation_guidestringrequired

The implementation guide the profile belongs to.

created_atstring (date-time)required

updated_atstring (date-time)required

Last update timestamp for the profile's current StructureDefinition. For retained versions, this equals created_at.

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/fhir/profiles/custom-patient/versions" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceType": "StructureDefinition",
  "id": "custom-patient",
  "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
  "version": "2.0.0",
  "name": "CustomPatient",
  "status": "active",
  "fhirVersion": "4.0.1",
  "kind": "resource",
  "abstract": false,
  "type": "Patient",
  "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
  "derivation": "constraint",
  "snapshot": {
    "element": [
      {
        "id": "Patient",
        "path": "Patient"
      }
    ]
  }
}'

201 CreatedExample Response

{
  "id": "custom-patient",
  "source": "custom",
  "resource_type": "Patient",
  "url": "http://phenoml.com/fhir/StructureDefinition/custom-patient",
  "version": "1.0.0",
  "status": "active",
  "date": "2026-08-24",
  "canonical": "http://phenoml.com/fhir/StructureDefinition/custom-patient|1.0.0",
  "fhir_version": "4.0.1",
  "implementation_guide": "acme-cardiology",
  "created_at": "2026-08-24T15:04:05Z",
  "updated_at": "2026-08-25T16:04:05Z"
}