API

The API is intended for developers who need to call Convert-Pheno from another application. Most users should use the command-line interface.

In some cases it is more convenient to send conversion requests over an HTTP(s) endpoint instead of calling the module directly. For that case, Convert-Pheno includes a lightweight REST API.

Basic request

Send a POST request to /api with a JSON body. Local examples below use plain http:// for simplicity, but the same API can also be exposed over https:// depending on deployment:

curl -d "@data.json" -H 'Content-Type: application/json' -X POST http://localhost:3000/api

Example payload:

{
  "conversion": "pxf2bff",
  "input": {
    "data": { "...": "..." }
  },
  "output": {
    "entities": ["individuals"]
  },
  "options": {
    "ohdsi_db": false
  }
}

The response is a JSON envelope with ok, data, and meta.conversion.

OpenAPI specification

The source schema for the Perl/Mojolicious wrapper lives in api/perl/openapi.json. A rendered OpenAPI reference is also available as Redoc.

JavaScript usage

The REST API is language-agnostic. JavaScript clients can call the same /api endpoint with the same JSON request body.

Browser fetch

    async function run() {
      const payload = {
        conversion: "pxf2bff",
        input: {
          data: {
            subject: {
              id: "P0007500",
              sex: "FEMALE"
            }
          }
        },
        output: {
          entities: ["individuals"]
        },
        options: {
          test: true
        }
      };

      const response = await fetch("http://localhost:3000/api", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify(payload)
      });

      const result = await response.json();

      if (!result.ok) {
        console.error(result.error);
      } else {
        console.log(result.data);
      }
    }

    run();

This browser example assumes the API is same-origin with the page, or that the deployment enables CORS.

Node.js fetch

    async function run() {
      const payload = {
        conversion: "pxf2bff",
        input: {
          data: {
            subject: {
              id: "P0007500",
              sex: "FEMALE"
            }
          }
        },
        output: {
          entities: ["individuals"]
        },
        options: {
          test: true
        }
      };

      const response = await fetch("http://localhost:3000/api", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify(payload)
      });

      const result = await response.json();

      if (!result.ok) {
        throw new Error(result.error.message);
      }

      console.log(result.meta.conversion);
      console.log(result.data);
    }

    run().catch(console.error);

Node.js 21+ includes stable built-in fetch. Older Node.js versions may require a polyfill such as undici.

Recommended API routes

The REST API works best for self-contained payloads where the request already carries the data needed for conversion.

Input family	REST API status	Why
BFF	Recommended	Small JSON payloads are natural to send over HTTP(s)
PXF	Recommended	Small JSON payloads are natural to send over HTTP(s)
OMOP-CDM	Recommended with care	Acceptable when the client transposes query results into the JSON shape expected by the API
CSV	Not recommended	Mapping-file-based conversion depends on extra artifacts and file semantics that are awkward to serialize into a clean public API
REDCap	Not recommended	Requires both project data and a REDCap dictionary plus mapping-file context
CDISC-ODM	Not recommended	Follows the same mapping-file-driven pattern as REDCap

For CSV, REDCap, and CDISC-ODM, the CLI is the preferred interface. Those routes are better treated as file conversions than as public REST calls.

Available implementations

The repository currently includes two API wrappers:

• Perl: api/perl
• Python: api/python

The Perl implementation is the direct wrapper around the main module. The Python implementation exists for interoperability and calls the Perl conversion layer through an internal JSON bridge, so the core conversion logic still lives in Perl.

Client applications in JavaScript can consume the same REST API without needing a dedicated JavaScript server wrapper.

Deployment note

This API is intended to run on a machine where Convert-Pheno and its dependencies are already installed. In practice, the containerized setup is the easiest way to expose it as a local service. The Perl/Mojolicious wrapper is configured for HTTPS when run with hypnotoad, while the Python/FastAPI wrapper is typically served over HTTP(s) in local uvicorn examples depending on whether TLS is configured directly or terminated upstream.

See:

• Download & Installation
• Docker Installation