Skip to content

Datasets, downloads and uploads

A dataset is one published interaction map, such as an interactome screen or a literature curation, loaded into the portal. Every interaction belongs to at least one dataset. Reading datasets and downloading them is public. Changing them requires an administrator account.

The upload file formats are described in Data file formats.

Reading datasets

GET /api/datasets

Every dataset, ordered by ID. No authentication, no pagination.

A dataset from the reference portal:

{
  "id": 1,
  "dataset_reference": "25416956",
  "dataset_author": "Rolland T et al.",
  "year": "2014",
  "description": null,
  "interaction_status": "published",
  "name": "Lit-BM",
  "citation": "Rolland T et al. (2014). A proteome-scale map of the human interactome network. Cell.",
  "number_of_interactions": "13441",
  "pubmed_id": "25416956",
  "author": "Rolland T et al.",
  "title": "A proteome-scale map of the human interactome network",
  "journal": "Cell",
  "doi": "10.1016/j.cell.2014.10.050",
  "url": "https://pubmed.ncbi.nlm.nih.gov/25416956/",
  "publication_status": "published",
  "about_heading": "",
  "about_body": "",
  "show_on_about": true,
  "about_order": 0
}
Key Contents
name The dataset's name, unique in practice. Uploading again under the same name adds to the existing dataset.
citation A ready-formatted reference, Author (Year). Title. Journal., built from whichever parts are set. null when none are.
number_of_interactions Interactions linked to the dataset, as a string. Recounted after every import and delete. The count includes interactions marked removed.
interaction_status A free-text label chosen at upload, such as published. It is descriptive only: search does not filter or colour by it.
publication_status published, preprint or unpublished.
about_heading, about_body, show_on_about, about_order The dataset's section on the portal's About page. The heading falls back to the dataset name when empty.
dataset_reference, dataset_author Older names for pubmed_id (or "") and author (or "Unpublished Dataset"), kept for compatibility with the original openPIP.

GET /api/datasets/{pk}

One dataset, in the same shape. No authentication.

Status Body
404 {"detail": "Not found."}

Downloading

GET /api/datasets/{pk}/download

The dataset's interactions as a file attachment, generated from the database. No authentication. Interactions marked removed are left out.

Parameter Notes
fmt tab (default), sif or csv. Any other value gives tab.

tab: tab-separated, four columns, opening with # comment lines that cite the dataset's publication:

# openPIP dataset: Lit-BM
# Please cite: Rolland T et al. (2014). A proteome-scale map of the human interactome network. Cell.
# https://doi.org/10.1016/j.cell.2014.10.050
#ID(s) interactor A ID(s) interactor B  Confidence value(s) Publication identifier(s)
uniprotkb:P23511-2  uniprotkb:Q13952-2  score:0.90908535    pubmed:25416956

Each interactor is written as uniprotkb:<accession>, or its gene name when it has no accession. The confidence column is score:<value>, or - when there is none.

This is not standard PSI-MI TAB. In PSI-MI TAB, columns 3 and 4 hold alternative identifiers, but here they hold the score and publication. If you upload the file to a portal again, the interactions load (columns 1 and 2) but their scores do not. For standard PSI-MI TAB (15 to 46 columns), use the PSICQUIC service.

sif: one <A> interacts <B> line per interaction, for Cytoscape. Each protein is named by its gene name, else its UniProt accession, else its database ID. No header, no citation.

csv: columns gene_a,gene_b,uniprot_a,uniprot_b,score,dataset. No citation.

Note

No format marks negative interactions (reported non-interactions). They are exported like positive ones. Use PSICQUIC (column 36) if you need the flag.

Status Body
404 {"detail": "Not found."}

GET /api/datasets/download/

Every dataset in one ZIP file, datasets.zip, holding one <name>.tab file per dataset in the tab format above (spaces in names become _). No authentication. The server builds the archive once and reuses it until data changes.

GET /api/files/public

Additional files an administrator has published on the Downloads page, newest first. No authentication.

[{"id": 3, "file_name": "HuRI_isoforms.fasta", "file_size": 1048576,
  "show": true, "uploaded_at": "2026-09-02T10:15:00Z"}]

GET /api/files/{pk}/download

Download one of those files. No authentication for published files. Files an administrator has hidden can only be downloaded by administrators.

Status Body
403 {"detail": "Not found."}: the file is hidden.
404 No such file.

Managing datasets

Everything below requires an administrator account.

PATCH /api/datasets/{pk}

Edit a dataset's description, status, citation or About-page section. Send only the fields to change. An empty string clears a field.

Field Validation
description Up to 1,000 characters.
interaction_status Up to 100 characters.
pubmed_id Digits only, up to 8.
doi Must look like 10.1038/s41586-020-2188-x. A pasted https://doi.org/... or doi: prefix is removed.
author Up to 100 characters.
year Four digits.
title, journal Up to 500 and 300 characters.
url A URL.
publication_status published, preprint or unpublished.
about_heading Up to 200 characters.
about_body Free text.
show_on_about Boolean.
about_order Integer. Lower numbers come first on the About page.

The dataset's name cannot be changed. Returns the updated dataset.

Status Body
400 Field errors, e.g. {"pubmed_id": ["A PubMed ID must be digits only, e.g. 25416956."]}
404 {"detail": "Not found."}

DELETE /api/datasets/{pk}

Delete a dataset, together with every interaction that belongs to no other dataset. Interactions shared with another dataset stay. This cannot be undone.

{"orphaned_interactions_deleted": 1520}

Proteins are never deleted, even when no interactions remain.

GET /api/datasets/citation-lookup

Look up a publication to fill in a dataset's citation. Nothing is saved.

Parameter Notes
pubmed_id Looked up in NCBI PubMed.
doi Used when pubmed_id is not given. Looked up in Crossref.
{"pubmed_id": "25416956", "doi": "10.1016/j.cell.2014.10.050",
 "title": "A proteome-scale map of the human interactome network",
 "journal": "Cell", "year": "2014", "author": "Rolland T et al.",
 "url": "https://pubmed.ncbi.nlm.nih.gov/25416956/"}
Status Body (detail)
400 Provide either pubmed_id or doi.
400 A PubMed ID must be digits only, e.g. 25416956.
502 The external service failed or did not know the identifier.

Uploading interactions

The portal's upload wizard uses import-async: the file is processed in the background while the wizard polls for progress. The other upload endpoints are older routes that the web interface does not use.

POST /api/datasets/import-async

Start a background import. Multipart form data.

Field Notes
file Required. PSI-MI TAB (.tab, .tsv, .txt) or simple CSV (.csv). Other extensions are recognised by content.
dataset_name Required. An existing name adds to that dataset.
interaction_status Label for a new dataset. Default published.
category_id Optional ID of an interaction category to add every interaction in the file to, new or reused.
citation and About fields Optional, as for PATCH /api/datasets/{pk}. Validated before the import starts.

Returns 202 {"task_id": "..."}. Needs the Celery worker to be running.

Status Body
400 {"detail": "No file provided."} or {"detail": "dataset_name required."}
400 {"category_id": "Must be a category id."} or {"category_id": "No such category."}
400 Citation field errors.

GET /api/datasets/import-async/{task_id}

Progress of a background import.

{
  "task_id": "1f0c...",
  "status": "PROGRESS",
  "stage": "parsing",
  "progress": 40,
  "proteins_created": 12,
  "interactions_created": 830,
  "interactions_skipped": 4,
  "errors": []
}
Key Contents
status PENDING (queued or unknown), STARTED, PROGRESS, SUCCESS or FAILURE.
stage parsing, then enriching_uniprot, enriching_ensembl, enriching_organisms (each with a _warn variant if that external service failed), then done.
progress 0–100.
interactions_skipped Rows whose interaction already existed. The existing interaction is credited to this dataset as well.
errors Up to 50 {"row": n, "reason": "..."} entries per batch of 300 rows.

After the interactions are stored, new proteins are filled in from UniProt and Ensembl, and new organisms from NCBI Taxonomy. These steps need outbound internet access. Status is kept for one hour after the import ends. After that, status reads PENDING.

POST /api/datasets/check-proteins

Count how many of a list of identifiers the portal already knows. The upload wizard uses this for its preview.

{"identifiers": ["uniprotkb:P04637", "TP53", "Q00987"]}
{"existing": 2}

A prefix: is stripped from each identifier before matching. Identifiers are matched the way the import matches them: ignoring capitalisation, against the identifier table and each protein's UniProt, Ensembl, Entrez and gene-name fields. existing counts distinct identifiers.

POST /api/datasets/preview

Estimate what uploading a PSI-MI TAB file would do, without saving anything. Multipart form data with file and dataset_name (required but not used). Returns the same keys as an import result (proteins_created, proteins_existing, interactions_created, ...), with dry_run: true. interactions_created is the number of data rows, and interactions_skipped is always 0.

POST /api/datasets/upload

Import a PSI-MI TAB file during the request, with no background job and no UniProt enrichment. Same fields as import-async, except that CSV is not recognised. Returns 201 with the import result:

{
  "dry_run": false,
  "rows_sampled": null,
  "proteins_created": 12,
  "proteins_existing": 1648,
  "interactions_created": 830,
  "interactions_skipped": 4,
  "errors": [],
  "new_protein_ids": [20511, 20512],
  "new_organism_ids": []
}

If the citation fields fail validation, the response is 400. The interactions have already been stored by then.

POST /api/datasets/upload-rows

Import PSI-MI TAB lines sent as JSON, one batch per request.

Field Notes
lines Required, non-empty list of tab-separated lines.
dataset_name Required.
interaction_status, category_id As for import-async.
is_last_batch Send true on the final batch: only then are citation fields applied and dataset counts refreshed.

Each request stores its batch independently. Returns 201 with the import result.

POST /api/upload/

The oldest upload route. Multipart field file, PSI-MI TAB only. It links the interactions to no dataset, so they do not appear in dataset counts or downloads. Use import-async instead.

Managing published files

Files on the Downloads page other than the generated dataset downloads, such as sequence files or supplementary tables. Administrator only.

GET /api/files

Every uploaded file, published or hidden, newest first. Same object shape as GET /api/files/public.

POST /api/files

Upload a file. Multipart form data.

Field Notes
file Required. .fasta, .fa, .tab, .tsv, .sif or .csv, up to 500 MB, and valid UTF-8 text.
force true to keep both files when one with the same name exists.

New files are published straight away. Returns 201 with the file object.

Status Body
400 {"detail": "No file provided."}, the size limit, a disallowed extension, or File does not appear to be valid UTF-8 text.
409 {"detail": "collision", "file_name": "..."}: a file with this name exists. Resend with force.

PATCH /api/files/{pk}

Publish or hide a file: {"show": false}.

DELETE /api/files/{pk}

Delete the file from disk and from the list. Returns 204.