API

The Mojolicious API accepts self-contained JSON and registry-defined multipart uploads. Use the command-line interface for streaming and large datasets.

Endpoints

Method	Path	Purpose
GET	/api/health	Check the local Perl service
GET	/api/conversions	Get routes, input shapes, options, entities, maturity, and current resource availability
POST	/api/conversions/{conversion}	Run one conversion and return serialized artifacts

Read route options and current resource availability from the catalog instead of maintaining a separate conversion list in the client.

Conversion request

{
  "input": {
    "data": { "phenopacket": { "id": "P0007500" } }
  },
  "output": {
    "entities": ["individuals", "biosamples"]
  },
  "options": {}
}

Send it to the route selected from the catalog:

curl --fail-with-body \
  --header 'Content-Type: application/json' \
  --data @request.json \
  http://127.0.0.1:3000/api/conversions/pxf2bff

The HTTP boundary rejects client-supplied filesystem paths. OMOP can be sent as an object keyed by table name or uploaded as table files.

Multipart request

For file-based routes, inspect input.files in the selected catalog entry. It defines the required part names, accepted extensions, and whether a role may be repeated. Put output and options in the JSON-valued request part:

Entity-aware OMOP, PXF, FHIR, openEHR, i2b2, PCORnet, and Sentinel BFF routes advertise an optional mapping role for compact dataset and cohort metadata. Their PXF and OMOP output routes do not advertise this role because those outputs do not emit BFF dataset or cohort entities.

curl --fail-with-body \
  --form 'request={"output":{"entities":["individuals"]},"options":{"separator":","}}' \
  --form source=@records.csv \
  --form mapping=@mapping.yaml \
  http://127.0.0.1:3000/api/conversions/csv2bff

Uploads are synchronous, limited to 100 MiB per request, and removed from the private temporary workspace when the request finishes.

Artifact response

{
  "ok": true,
  "artifacts": [{
    "id": "individuals",
    "filename": "individuals.json",
    "mediaType": "application/json",
    "kind": "json",
    "encoding": "utf-8",
    "content": "[\n  { ... }\n]\n"
  }],
  "warnings": [],
  "meta": { "conversion": "pxf2bff" }
}

content is already serialized by Perl using the same conventions as the CLI. Text artifacts use encoding: "utf-8"; XLSX audit artifacts use base64. Clients should download it directly rather than rebuilding JSON or CSV. BFF outputs contain one artifact per requested entity; OMOP outputs contain one CSV artifact per emitted table.

Warnings are returned without logging phenotype payloads. Error statuses are:

• 404: unknown conversion
• 413: multipart request exceeds 100 MiB
• 422: invalid request or conversion failure
• 503: required local resource unavailable
• 500: unexpected service or bridge failure

Successful conversion does not imply external schema validation.

When a terminology report is requested, meta.terminologyAudit contains complete counts grouped by review_action and at most 100 preview rows per action. reportArtifactId identifies the complete XLSX or TSV in artifacts. The preview is intended for interactive review; the artifact remains the full audit record.

JavaScript example

async function convertPhenopacket(phenopacket) {
  const catalogResponse = await fetch('/api/conversions');
  const catalog = await catalogResponse.json();
  const route = catalog.data.find(({id}) => id === 'pxf2bff');

  if (!route?.available) {
    throw new Error(route?.unavailableReason ?? 'Conversion is unavailable');
  }

  const response = await fetch(`/api/conversions/${route.id}`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      input: {data: phenopacket},
      output: {entities: ['individuals']},
      options: {},
    }),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error.message);

  return result.artifacts; // serialized content is ready to download
}

Server implementations

Perl / Mojolicious

The official graphical application uses Mojolicious, supports JSON and multipart routes, and calls the shared Perl service directly:

morbo -l http://127.0.0.1:3000 api/perl/main.pl

Python / FastAPI

FastAPI is a smaller JSON-only reference wrapper over the internal Perl bridge. Its catalog excludes multipart-only routes:

cd api/python
uvicorn main:app --host 127.0.0.1 --port 8000

Planned Python HTTP API deprecation

The Python HTTP API is retained temporarily for compatibility with existing JSON integrations and published descriptions. As file uploads, multi-file inputs, and downloadable artifacts expand, it will be deprecated in favor of the Mojolicious API. New HTTP(s) integrations should use Mojolicious.

This does not deprecate the Python module binding.

The source OpenAPI specification and published Redoc reference describe the same contract.