Blueprint REST API

The website runs on this API. Call it from your own scripts to browse TCGA projects, run plot and analysis jobs, and download results.

Start the quickstartOpen the API reference

GET/api/projects?program=TCGA&pageSize=2

Example response, trimmed

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "TCGA-ACC",
        "name": "TCGA-ACC",
        "disease_type": "ACC",
        "program": "TCGA",
        "description": "Adrenocortical Carcinoma",
        "tissue_type": "Tumor",
        "case_count": 79,
        "file_count": 79
      },
      {
        "id": "TCGA-BLCA",
        "name": "TCGA-BLCA",
        "disease_type": "BLCA",
        "program": "TCGA",
        "description": "Bladder Urothelial Carcinoma",
        "tissue_type": "Tumor & Normal",
        "case_count": 431,
        "file_count": 431
      }
    ],
    "total": 33,
    "page": 1,
    "pageSize": 2,
    "totalPages": 17
  },
  "timestamp": 1790726400
}

The API at a glance

Base URL
https://blueprint.love, and every path starts with /api
Authentication
A bearer access token, valid 15 minutes by default. Browsing projects needs none.
Format
JSON in one envelope; figures and tables download as files.
Limits
Set per route. A refused call gets HTTP 429 and a Retry-After header.

Quickstart

Three steps to your first authenticated call, then on to jobs. The first step needs no account.

  1. List TCGA projects

    The project catalogue is public, so this works before you sign in.

    curl "https://blueprint.love/api/projects?program=TCGA&pageSize=5"

  2. Get an access token

    Sign in, open your Profile page and copy the token from the Access Token card. A token lasts 15 minutes from when it was issued by default, and the card shows how long it has left; a script that runs longer should sign in by itself. Keep the token out of your code: set it in the session you will call from. Input is hidden, and Enter finishes it.

    printf 'Paste your token: '; read -rs BLUEPRINT_TOKEN; echo
export BLUEPRINT_TOKEN

  3. Call an endpoint that needs the token

    Send it in the Authorization header. A 401 means it is missing or has expired.

    curl -H "Authorization: Bearer $BLUEPRINT_TOKEN" "https://blueprint.love/api/auth/me"

  4. Run a job

    Figures and analyses run in the background: you create a job, poll it until it finishes, then download the result. Follow Render a figure or Run an analysis.

Keep going