Documentation - Molecular AOP Builder

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://your-domain.com/api/v1/mappings?page=1&per_page=50"
curl "https://your-domain.com/api/v1/mappings?confidence=High&aop_id=1"
curl "https://your-domain.com/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

GET /api/v1/mappings/<uuid>

Get a single KE-WP mapping by its UUID.

curl https://your-domain.com/api/v1/mappings/abc12345-...

GET /api/v1/go-mappings

List KE-GO mappings with pagination and optional filters.

curl "https://your-domain.com/api/v1/go-mappings?page=1&per_page=50"
curl "https://your-domain.com/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://your-domain.com/api/v1/go-mappings/def67890-...

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://your-domain.com/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://your-domain.com/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://your-domain.com/suggest_pathways/55

Response: JSON object with ranked suggestions

GET /search_pathways

Search for pathways with fuzzy matching.

curl "https://your-domain.com/search_pathways?query=apoptosis&limit=10"

Parameters:

query - Search term (required)
limit - Max results (default: 10)
threshold - Similarity threshold (default: 0.3)

GET /suggest_go_terms/<ke_id>

Get GO Biological Process term suggestions for a specific Key Event, ranked by gene overlap and semantic similarity.

curl https://your-domain.com/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 (e.g. GO:0006915) with fuzzy matching.

curl "https://your-domain.com/search_go_terms?query=apoptosis&limit=10"
curl "https://your-domain.com/search_go_terms?query=GO:0006915"

GET /ke_genes/<ke_id>

Get gene associations for a specific Key Event.

curl https://your-domain.com/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://your-domain.com/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://your-domain.com/api/scoring-config

GET /api/go-scoring-config

Retrieve the current KE-GO assessment scoring configuration.

curl https://your-domain.com/api/go-scoring-config

GET /export/<format>

Export the mapping dataset in the specified format.

curl https://your-domain.com/export/csv -o mappings.csv
curl https://your-domain.com/export/json -o mappings.json
curl https://your-domain.com/export/excel -o mappings.xlsx
curl https://your-domain.com/export/rdf -o mappings.ttl

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

Authentication

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

GitHub OAuth authentication, or
Guest authentication via 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.

Sign in