API Documentation

The Molecular AOP Builder provides a public REST API for programmatic access to mapping data, plus internal endpoints used by the web interface.

Interactive docs: Browse and test all public API endpoints at /api/docs (Swagger UI). For code examples in Python and R, see the API Consumer Guide.

Public REST API (v1)

The /api/v1 endpoints are the recommended way to access mapping data. They support pagination, filtering, and CSV/JSON output. No authentication required.

GET /api/v1/mappings

List KE-WP mappings with pagination and optional filters.

curl "https://molaop-builder.vhp4safety.nl/api/v1/mappings?page=1&per_page=50"
curl "https://molaop-builder.vhp4safety.nl/api/v1/mappings?confidence=High&aop_id=1"
curl "https://molaop-builder.vhp4safety.nl/api/v1/mappings?format=csv" -o mappings.csv

Parameters:

  • page - Page number (default: 1)
  • per_page - Results per page (default: 50, max: 200)
  • confidence - Filter by confidence level (High, Medium, Low)
  • aop_id - Filter by AOP ID
  • format - Response format: json (default) or csv

Response shape: results are returned under data, with a pagination block carrying page, per_page, total, total_pages and ready-made next / prev URLs.

{
  "data": [
    {
      "uuid": "ed70e647-51c4-48c7-9ea9-132c243bb562",
      "ke_id": "KE 1790",
      "ke_name": "Increased, Differentiation to Testis",
      "ke_bio_level": "Tissue",
      "ke_aop_context": ["AOP 346", "AOP 376"],
      "pathway_id": "WP4842",
      "pathway_title": "Mammalian disorder of sexual development",
      "confidence_level": "high",
      "connection_type": "other",
      "assessment": {
        "relationship": null, "basis": null,
        "specificity": null, "coverage": null, "version": "v1"
      },
      "provenance": {
        "proposed_by": "github:marvinm2",
        "approved_by": "github:marvinm2",
        "approved_at": "2026-07-18T12:18:49.000031",
        "suggestion_score": null
      }
    }
  ],
  "pagination": { "page": 1, "per_page": 1, "total": 125, "total_pages": 125,
                  "next": "...", "prev": null }
}

The assessment block

Every mapping carries the curator's answers to the four-question confidence rubric, so a consumer can see why a mapping received its confidence level rather than only the verdict. The same envelope is emitted by the WP, GO and Reactome serializers.

  • relationship — how the KE and target relate (causative, responsive, …)
  • basis — strength of the underlying evidence
  • specificity — how tightly the target scopes to the KE
  • coverage — how much of the KE the target accounts for
  • version — v2 when the rubric answers were captured at submission; v1 for mappings approved before the rubric was persisted at column level, where the four answer fields are null

The envelope shape is identical for both versions, so a consumer never has to branch on its presence — only on version if the answers themselves are needed. The same five values are appended as columns in the CSV export.

GET /api/v1/mappings/<uuid>

Get a single KE-WP mapping by its UUID.

curl https://molaop-builder.vhp4safety.nl/api/v1/mappings/abc12345-...

GET /api/v1/go-mappings

List KE-GO mappings with pagination and optional filters.

curl "https://molaop-builder.vhp4safety.nl/api/v1/go-mappings?page=1&per_page=50"
curl "https://molaop-builder.vhp4safety.nl/api/v1/go-mappings?format=csv" -o go_mappings.csv

GET /api/v1/go-mappings/<uuid>

Get a single KE-GO mapping by its UUID.

curl https://molaop-builder.vhp4safety.nl/api/v1/go-mappings/def67890-...

GET /api/v1/reactome-mappings

List KE-Reactome mappings with pagination and optional filters. The Reactome ranker uses the same v1.5 pure-semantic approach; the underlying tab in the curator UI is in active refinement.

curl "https://molaop-builder.vhp4safety.nl/api/v1/reactome-mappings?page=1&per_page=50"
curl "https://molaop-builder.vhp4safety.nl/api/v1/reactome-mappings?format=csv" -o reactome_mappings.csv

Parameters: same shape as /api/v1/mappings — page, per_page, confidence_level, aop_id, format.

GET /api/v1/reactome-mappings/<uuid>

Get a single KE-Reactome mapping by its UUID.

curl https://molaop-builder.vhp4safety.nl/api/v1/reactome-mappings/abc12345-...

GET /api/v1/spec

Returns the raw OpenAPI 3.0 spec (YAML) used to render the Swagger UI at /api/docs. CORS-enabled, no rate limiting.

curl https://molaop-builder.vhp4safety.nl/api/v1/spec -o openapi.yaml

Internal Endpoints

These endpoints are used by the web interface. They are public but may change without notice.

GET /get_ke_options

Fetch available Key Events from pre-computed metadata.

curl https://molaop-builder.vhp4safety.nl/get_ke_options

Response: JSON array of Key Event objects

[
    {
        "KEid": "55",
        "KElabel": "Increase, CYP2E1",
        "KEbiologicalLevel": "Molecular"
    },
    ...
]

GET /get_pathway_options

Fetch available WikiPathways from pre-computed metadata.

curl https://molaop-builder.vhp4safety.nl/get_pathway_options

Response: JSON array of pathway objects

GET /suggest_pathways/<ke_id>

Get AI-powered pathway suggestions for a specific Key Event.

curl https://molaop-builder.vhp4safety.nl/suggest_pathways/55

Response: JSON object with ranked suggestions

GET /search_pathways

Search for pathways by title or description with fuzzy matching. A query that is a WikiPathways identifier resolves directly to that pathway.

curl "https://molaop-builder.vhp4safety.nl/search_pathways?q=apoptosis&limit=10"
curl "https://molaop-builder.vhp4safety.nl/search_pathways?q=WP554"

Parameters:

  • q - Search term (required)
  • limit - Max results (default: 20, max: 100)
  • threshold - Similarity threshold 0.1–1.0 (default: 0.4)
Identifier lookup: a query matching a WikiPathways ID (WP554, tolerating case and :/-/_ separators) returns that single pathway at relevance 1.0 rather than being fuzzy-matched against titles. A WP-prefixed ID that is not in the corpus returns an empty result set; a bare number is tried as an identifier and otherwise falls through to fuzzy matching.

GET /suggest_go_terms/<ke_id>

Get GO Biological Process term suggestions for a specific Key Event, ranked by BioBERT semantic similarity (v1.5). Gene overlap is returned for display purposes but does not influence the ordering.

curl https://molaop-builder.vhp4safety.nl/suggest_go_terms/55

Response: JSON object with ranked GO term suggestions including scores and matched genes.

GET /search_go_terms

Search GO terms by name or GO ID with fuzzy matching. Searches both the Biological Process and Molecular Function namespaces; each result carries a go_namespace field of BP or MF.

curl "https://molaop-builder.vhp4safety.nl/search_go_terms?q=apoptosis&limit=10"
curl "https://molaop-builder.vhp4safety.nl/search_go_terms?q=GO:0006915"

Parameters: q (required), limit (default: 10), threshold (default: 0.4).

A query matching a GO ID (GO:0006915, go:0006915, GO_0006915) resolves directly to that term at relevance 1.0.

GET /suggest_reactome/<ke_id>

Get Reactome pathway suggestions for a specific Key Event, using the same v1.5 pure-semantic ranker as WikiPathways and GO.

curl https://molaop-builder.vhp4safety.nl/suggest_reactome/55

GET /search_reactome

Search Reactome pathways by name or description. A query matching a Reactome stable identifier (R-HSA-109581, tolerating separators) resolves directly to that pathway.

curl "https://molaop-builder.vhp4safety.nl/search_reactome?q=apoptosis&limit=10"
curl "https://molaop-builder.vhp4safety.nl/search_reactome?q=R-HSA-109581"

Parameters: q (required), limit (default: 10), threshold (default: 0.4).

GET /ke_genes/<ke_id>

Get gene associations for a specific Key Event.

curl https://molaop-builder.vhp4safety.nl/ke_genes/55

GET /api/ke_context/<ke_id>

Get KE context: associated AOPs and any existing WP/GO mappings for a Key Event.

curl https://molaop-builder.vhp4safety.nl/api/ke_context/55

Response:

{
    "ke_id": "55",
    "aops": [{"aop_id": "1", "aop_title": "..."}],
    "wp_mappings": [{"pathway_id": "WP4726", "pathway_title": "...", "confidence": "High"}],
    "go_mappings": [{"go_id": "GO:0006915", "go_name": "apoptotic process"}]
}

GET /api/scoring-config

Retrieve the current KE-WP assessment scoring configuration.

curl https://molaop-builder.vhp4safety.nl/api/scoring-config

GET /api/go-scoring-config

Retrieve the current KE-GO assessment scoring configuration.

curl https://molaop-builder.vhp4safety.nl/api/go-scoring-config

GET /export/<format>

Export the mapping dataset in the specified format.

curl https://molaop-builder.vhp4safety.nl/export/csv -o mappings.csv
curl https://molaop-builder.vhp4safety.nl/export/json -o mappings.json
curl https://molaop-builder.vhp4safety.nl/export/excel -o mappings.xlsx
curl https://molaop-builder.vhp4safety.nl/export/rdf -o mappings.ttl

Supported formats: csv, tsv, json, excel, rdf

Per-resource GMT and RDF exports

These serve one resource at a time and are what the /downloads page links to. No authentication, no rate limit — they are static cached files regenerated when mappings change.

GMT gene sets

Two shapes per resource. The plain route emits one gene set per mapping; the -centric route emits one gene set per Key Event, taking the union of genes across all that KE's approved mappings in that resource. For KE-level enrichment with fgsea or clusterProfiler you almost always want the -centric variant — otherwise a KE mapped to four pathways contributes four competing sets.

curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-wp -o ke-wp.gmt
curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-wp-centric -o ke-wp-centric.gmt

# same pair for the other two resources
curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-go -o ke-go.gmt
curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-go-centric -o ke-go-centric.gmt
curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-reactome -o ke-reactome.gmt
curl https://molaop-builder.vhp4safety.nl/exports/gmt/ke-reactome-centric -o ke-reactome-centric.gmt

All six GMT routes accept an optional min_confidence filter (high, medium or low); omit it for every approved mapping regardless of tier.

curl "https://molaop-builder.vhp4safety.nl/exports/gmt/ke-wp-centric?min_confidence=high" -o ke-wp-high.gmt

RDF / Turtle

Turtle serialisations carrying full curation provenance (proposer, approver, approval timestamp, confidence, and the assessment answers), suitable for SPARQL federation against AOP-Wiki RDF.

curl https://molaop-builder.vhp4safety.nl/exports/rdf/ke-wp -o ke-wp.ttl
curl https://molaop-builder.vhp4safety.nl/exports/rdf/ke-go -o ke-go.ttl
curl https://molaop-builder.vhp4safety.nl/exports/rdf/ke-reactome -o ke-reactome.ttl
Citing a fixed version: these endpoints always serve the current state of the database. For a citable, frozen snapshot use the Zenodo deposit instead — concept DOI 10.5281/zenodo.20184643 always resolves to the latest version, and each version bundles the same GMT and Turtle files split by confidence tier. Released under CC0.

Authentication

The v1 public API requires no authentication. Internal mutation endpoints (POST /submit, POST /submit_go_mapping, POST /submit_reactome_mapping, POST /submit_proposal) require:

  • GitHub OAuth sign-in, or
  • Guest authentication via a workshop access code
  • CSRF token in request headers

Rate Limiting

API endpoints are rate-limited via Flask-Limiter:

  • Public API (v1): 100 requests/hour per IP
  • Internal endpoints: 500 requests/hour per IP

When the limit is exceeded the API returns HTTP 429 Too Many Requests.