Skip to content

Site settings and administration

Endpoints behind the portal's admin panel: appearance and text, announcements, interaction categories and administrator accounts. Reading settings, text, announcements, counts and categories is public, because every page needs them. Every change requires an administrator account.

Site settings

GET /api/settings

The portal's configuration: titles, colours, page content and feature switches. Returns {} on a portal that has never been configured.

From the reference portal (long values shortened):

{
  "title": "openPIP: Protein Interaction Portal",
  "shortTitle": "openPIP",
  "url": "https://openpip.usask.ca/",
  "version": "2.0",
  "mainColorScheme": "#0f766e",
  "mainColorScheme2": "#06b6d4",
  "gradientAngle": 135,
  "navStyle": "solid",
  "queryNodeColor": "#e11d48",
  "interactorNodeColor": "#0f766e",
  "showTissueExpression": true,
  "showSubcellularLocation": true,
  "horizontalFilterBar": true,
  "example1": "TP53",
  "example1Type": "None",
  "faq": "<h2>Getting started</h2>...",
  "logoUrl": null,
  ...
}
Keys Meaning
title, shortTitle Full and short portal name.
url, version Shown on the About page.
logoUrl Path of the uploaded logo, or null. Read-only. Set it with POST /api/settings/logo.
mainColorScheme, mainColorScheme2, gradientAngle Primary colour, second colour and angle (degrees) for gradient headers.
headerColorScheme, logoColorScheme, buttonColorScheme Header text, logo and button colours.
navStyle Navigation bar style: solid, gradient or light.
navStyleOverrides Per-page navigation styles, e.g. home:gradient,search:solid.
queryNodeColor, interactorNodeColor Network colours for the proteins searched for and for their partners.
publishedEdgeColor, validatedEdgeColor, verifiedEdgeColor, literatureEdgeColor Network edge colours. Each edge takes the colour for its highest interaction category order: 1, 2, 3 and 4 use these four in turn, whatever the categories are called. Any other order is drawn grey (#cccccc).
canvasBackgroundColor Network canvas background, or null for the default.
proteinLinkTarget Where gene names in the search result tables link: ncbi (NCBI Gene, the default), protein_page (this portal's protein page) or custom.
proteinLinkTemplate For custom: an http:// or https:// URL in which {gene}, {uniprot}, {entrez} and {ensembl} are replaced by the protein's URL-encoded identifiers. Other schemes are rejected with 400, as is custom without a template.
horizontalFilterBar true puts the search page's filters in a ribbon above the network instead of a side panel.
showTissueExpression, showSubcellularLocation Turn off for portals whose organism has no such annotations.
showDownloads, showDownloadAll Show the dataset table and the supplementary files section of the Downloads page ("Show Dataset Downloads" and "Show Supplementary Files" in the admin panel). They hide links only, as in the original openPIP: the download endpoints stay available.
example1, example2, example3 Example searches offered on the home page.
example1Type, example2Type, example3Type Network filter for each example: None, query-query or query-interactor (see search filters).
about, faq, contact, download, footer, homePage Page content as HTML.
missionTitle, missionText, methodTitle, methodText Home page text. Read-only here. Change it through site text.

PATCH /api/settings

Change any of the keys above (except the read-only ones). Send only the keys to change. Returns the full settings.

Status Body
400 Field errors, e.g. {"gradientAngle": ["A valid integer is required."]}

Upload the portal logo. Multipart form data, field logo: PNG, JPEG, GIF, SVG or WebP. Replaces any existing logo. Returns the full settings.

Status Body (detail)
400 No file provided.
400 Unsupported file type.

Remove the logo. Returns {"detail": "Logo removed."}.

Site text

Every label and paragraph in the interface has a built-in default. An administrator can override any of them. This endpoint stores only the overrides. The interface falls back to its defaults for everything else.

GET /api/settings/text

Parameter Notes
locale Language code, default en, e.g. en or fr-CA.
{"locale": "en", "text": {"nav.home": "Home", "home.mission.heading": "<h4>Our Mission</h4>"}}
Status Body (detail)
400 Invalid locale.

PUT /api/settings/text

Add, change or remove overrides in one request. Takes the same locale parameter.

{"entries": [
  {"key": "nav.home", "value": "Start"},
  {"key": "home.mission.heading", "value": null}
]}

A null or missing value removes the override, so the built-in default applies again. An empty string is kept, which deliberately blanks that text. Keys are up to 200 characters. Returns all overrides for the locale, as GET does.

Status Body
400 {"detail": "Expected a list under 'entries'."}
400 Field errors, e.g. a blank key.

Announcements

GET /api/announcements

Announcements for the home page, newest first. No authentication. An announcement is listed only when both show and showOnHomePage are true. The admin panel's Hide turns show off.

For example:

[{"id": 7, "title": "New dataset", "text": "<p>HuRI isoforms are now searchable.</p>",
  "date": "2026-09-30T12:00:00Z", "show": true, "showOnHomePage": true}]

text is HTML.

GET /api/admin/announcements

Every announcement, newest first.

POST /api/admin/announcements

Field Notes
title Required, up to 100 characters.
text Required, up to 4,000 characters.
showOnHomePage Required, boolean.
date Date and time, or null.
show Boolean, default true.

Returns 201 with the announcement.

PATCH /api/admin/announcements/{pk}

Change some fields. Returns the announcement, or 404 {"detail": "Not found."}.

DELETE /api/admin/announcements/{pk}

Returns 204, or 404.

Counts

GET /api/counts

The totals shown on the home page. No authentication.

{"proteins": 20015, "interactions": 122933, "datasets": 10}

interactions excludes interactions marked removed.

Interaction categories

Categories group interactions by kind of evidence, such as published, validated, verified or literature-curated. Each interaction can belong to several. Readers can filter the network by category, and each edge is coloured by its highest-order category through the edge colour settings. A category's own colorScheme is stored for compatibility with the original openPIP, which did not display it either. The admin panel shows each category the edge colour its order gives.

GET /api/interaction-categories

No authentication. From the reference portal:

[
  {"id": 1, "categoryName": "Published", "order": "1", "colorScheme": "#38761d",
   "description": "Published interactions from peer-reviewed sources."},
  {"id": 2, "categoryName": "Validated", "order": "2", "colorScheme": "#1155cc",
   "description": "Validated interactions from high-throughput experiments."}
]

Sorted by the numeric value of order, which is stored as a string.

POST /api/interaction-categories

Create a category with categoryName, order, colorScheme and description. Returns 201.

PATCH /api/interaction-categories/{pk}

Change some fields. Returns the category, or 404 {"detail": "Not found."}.

DELETE /api/interaction-categories/{pk}

Delete the category, and with it every interaction's membership in it. The interactions themselves stay. Returns 204, or 404.

Administrator accounts

New accounts are never administrators. An existing administrator promotes them. The first administrator is created on the server; see Installation.

GET /api/admin/users

All accounts, administrators first, then by username.

Parameter Notes
search Matches part of the username or email.

For example:

[{"id": 1, "username": "admin", "email": "admin@example.org",
  "isAdmin": true, "isSuperuser": true, "dateJoined": "2026-05-11T09:00:00Z"}]

PATCH /api/admin/users/{pk}

Grant or revoke administrator access: {"isAdmin": true}. The change applies to the account's API requests immediately. Its interface shows or hides the admin panel at its next token refresh, within an hour.

Status Body
400 {"isAdmin": "Expected true or false."}: the value must be a JSON boolean.
400 {"isAdmin": "You cannot revoke your own admin access."}
400 {"isAdmin": "Superusers cannot have their admin access revoked."}
404 {"detail": "Not found."}

Refusing to revoke your own access means a portal can never be left without an administrator from inside the admin panel.