HIPPIE
REST API

Contents

• Overview
• Shared filter parameters
• Filter options
• Protein query
• Batch pairwise lookup
• Network expansion
• Browse (paginated)
• Bulk export (TSV)
• Machine-learning splits

Overview

All paths below are relative to the HIPPIE base URL and return application/json unless noted otherwise. Parameters marked (repeatable) may be supplied more than once (e.g. &source=1&source=2).

If you would rather let an AI assistant query HIPPIE, the same data is also served over the Model Context Protocol — see AI assistants (MCP) on the download page.

Shared filter parameters

Accepted by most endpoints. Their meaning is explained in the filter guide.

• show = interactions, noninteractions or both.
• min_score / max_score = confidence-score bounds (0–1).
• source, experiment, interaction_type, tissue = numeric ids (repeatable), listed by the filter options endpoint. Values within one parameter are OR-ed; different parameters are AND-ed. Omit a parameter to disable that filter — there is no way to request "none of them", because a result matching no source database does not exist.
• min_tpm = minimum tissue expression (used together with tissue).
• min_degree, min_avg_score = protein-level thresholds, both measured across all of HIPPIE rather than within the filtered result set.
• reviewed = reviewed, unreviewed, or both.
• isoform_mode = general, isoforms, or both.

Back to top

Filter options

The vocabulary behind the filter lists, i.e. the numeric ids that the source, experiment, interaction_type and tissue parameters (and source_ids, experiment_ids, type_ids, tissue_ids for ML splits) expect. Takes no parameters. Returns { tissues[], sources[], experiments[], interaction_types[], category_order }; each option is { id, name, category, count } (tissues also carry a subcategory). For sources, experiment and interaction types count is the number of interactions carrying that evidence; for tissues it is the number of genes expressed there. Options that no interaction uses are omitted. category_order gives the display order of the categories for each list.

Back to top

Protein query

Interactions of one or more proteins. q accepts up to 50 identifiers (separated by comma, space or tab) — each a gene symbol, UniProt accession or entry name, Entrez id, isoform accession, or Ensembl id (ENSG/ENST). Each is resolved independently and the interactions are returned as one combined list; the shared filters apply. Returns { query_proteins, isoforms_included, expanded_proteins, unresolved, interactions[], error }, where unresolved lists any inputs that matched nothing (the request still succeeds for the rest).

Back to top

Batch pairwise lookup

Looks up the recorded interaction for each supplied pair. Body: { "pairs": [ { "a": "TP53", "b": "MDM2", "input_order": 0 } ], … filters } (up to 200 pairs per request). Returns { results: [ … ] }; a row with score = -1.0 means that pair was not found.

Back to top

Network expansion

Builds the first-shell sub-network around a set of seed proteins (every edge touching a seed). Body: { "proteins": "TP53 BRCA1 ATM", … filters } (identifiers separated by whitespace, commas or semicolons). Returns { node_count, edge_count, interactions[], seed_ids, unresolved, truncated, total_edges, error }.

Back to top

Browse (paginated)

/api/browse/proteins/ returns a page of proteins { total, proteins[] } (each protein carries degree, avg_score and is_reviewed); /api/browse/interactions/ returns a page of interactions { total, interactions[] }. Both accept offset, limit (≤ 200), a free-text search field q (up to 50 identifiers separated by comma, space or tab — matches are unioned), sort/dir, and the shared filters.

Back to top

Bulk export (TSV)

Streams the filtered result set as a tab-separated file (mode=proteins or mode=interactions, using the same filters as the matching browse endpoint). Capped at 50 000 rows; the response sets the header X-Export-Truncated: 1 when the cap is reached.

Back to top

Machine-learning splits

Building a split is a background job, so it runs in three steps: POST the parameters to start it, poll the job until it reports DONE, then download the archive. Unlike the endpoints above, these take a JSON request body (Content-Type: application/json) rather than query parameters, and the vocabulary filters are arrays named source_ids, experiment_ids, type_ids and tissue_ids instead of the repeatable singular source, experiment, interaction_type and tissue.

POST /api/browse/splits/ queues a job and answers 202 with { job_id, status }. POST /api/browse/splits/stats/ takes the same body but runs no job — it returns { protein, interaction } summary statistics for the filter set, which is what the preview boxes on the ML Splits page show. GET /api/browse/splits/<job_id>/ reports { status, step, progress, params, created_at, started_at, queue_position, estimated_wait_seconds, cancel_requested, summary, error, download_url }; status is PENDING, RUNNING, DONE, FAILED or CANCELLED, and download_url is filled in only once the job is DONE. Splits are generated one at a time and a run takes from tens of minutes up to 3 hours (the run cap, SPLIT_JOB_MAX_RUN_SECONDS; a run past it is stopped and fails), so poll no more than once every few seconds and read elapsed time from started_at rather than created_at — a job can wait in the queue far longer than it runs. The queue is first-come-first-served and neither capped nor deduplicated, so estimated_wait_seconds (seconds until the job is expected to start, null once it has) is the honest cost of submitting during a busy period. It is an estimate: the median duration of recent successful runs times the number of jobs ahead, less whatever is left of the run in progress. Finished jobs are kept for a limited period and then deleted along with their archive, so download a split you care about rather than relying on the job id indefinitely. POST /api/browse/splits/<job_id>/cancel/ stops a queued or running job: 200 when it was PENDING (cancelled outright), 202 when it was RUNNING (the pipeline is signalled and the job reaches CANCELLED within about ten seconds), and 409 when it has already finished. GET /api/browse/splits/<job_id>/download/ then streams the ZIP archive; it answers 404 until the job is DONE.

The archive holds four labelled CSVs, each protein1,protein2,label[,score] with label 1 for interacting and 0 for not:

• train.csv, val.csv, test_balanced.csv — 1:1 positives to negatives, negatives chosen by an ILP that matches degree, taxon-pair, self-loop and GO-Jaccard bias.
• test_realistic.csv — 1:10, with uniform negatives. It simulates an uncontrolled screen, so it is deliberately not bias-matched.
• sequences.fasta — the sequence of every protein in the four CSVs, headed by the same UniProt accession.
• summary.json and README.txt, naming the filters used, the per-split counts, and the exact pipeline commit the split was cut with.

Splits are leakage-aware by sequence homology and not only by graph cut: the positives are partitioned by an ILP over a precomputed sequence-similarity clustering of the proteome, and CD-HIT-2D then removes train/test pairs that remain homologous. Expect materially fewer pairs than the raw filtered interaction count.

Accepted body keys (all optional — every one has a default):

• min_score / max_score = confidence-score bounds (0–1, default 0 and 1).
• source_ids, experiment_ids, type_ids, tissue_ids = arrays of numeric ids. An empty or omitted array applies no filter.
• min_tpm = minimum tissue expression, used together with tissue_ids.
• min_degree_global, min_avg_score = protein-level thresholds, both evaluated over the whole database rather than the filtered subgraph. The older name min_degree is still accepted.
• isoform_mode = general, isoforms or both.

neg_ratio and seed are no longer accepted. The negative ratio is fixed per split (1:1, and 1:10 for test_realistic.csv) and the seed is a pipeline parameter, so both are properties of the pipeline rather than of a request. Bodies that still carry them are accepted and the keys ignored.

Raw data instead of a split. POST /api/browse/splits/raw/ takes the same body but builds no split: it exports the filtered interactions (ppis.csv), any matching curated non-interactions (candidate_negatives.csv), a ready-made samplesheet.csv and a README.txt, for running the ppi-splitting-pipeline yourself (see the Machine Learning guide). It runs immediately and answers 201 with { job_id, status }; the job is already DONE (or FAILED when the filters leave nothing to export), and the ZIP is fetched from the same download/ endpoint.

Out-of-range values answer 400 with the failing constraint in the message. Ready-made splits of the current release, if you do not need your own filters, are on the download page.

Back to top