API Endpoints

POST /v1/query

curl -X POST https://api.bioquery.io/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Is DDR1 expression higher in papillary RCC vs clear cell RCC?"
  }'

{
  "id": "card_abc123xyz",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "query": {
    "original": "Is DDR1 expression higher in papillary RCC vs clear cell RCC?",
    "parsed": {
      "gene": "DDR1",
      "cancer_types": ["KIRP", "KIRC"],
      "analysis_type": "differential_expression"
    },
    "sql": "SELECT sample_id, cancer_type, gene_expression FROM tcga.expression WHERE gene_symbol = 'DDR1' AND cancer_type IN ('KIRP', 'KIRC')"
  },
  "results": {
    "answer": "DDR1 expression is significantly higher in papillary RCC (KIRP) compared to clear cell RCC (KIRC), with a 2.3-fold increase (p < 0.001, Wilcoxon rank-sum test).",
    "statistics": {
      "p_value": 0.00032,
      "fold_change": 2.3,
      "effect_size": 0.85,
      "test": "wilcoxon_ranksum"
    },
    "sample_sizes": {
      "KIRP": 290,
      "KIRC": 533
    }
  },
  "figure": {
    "type": "boxplot",
    "plotly_json": { ... }
  },
  "methods": "Gene expression data were obtained from The Cancer Genome Atlas (TCGA). DDR1 mRNA expression (log2 TPM+1) was compared between papillary renal cell carcinoma (KIRP, n=290) and clear cell renal cell carcinoma (KIRC, n=533) using a Wilcoxon rank-sum test."
}

GET /v1/cards/{card_id}

curl https://api.bioquery.io/v1/cards/card_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/cards/{card_id}/methods

curl https://api.bioquery.io/v1/cards/bq-2025-01-15-a7f3x/methods \
  -H "Authorization: Bearer YOUR_API_KEY"

Gene expression data were obtained from The Cancer Genome Atlas (TCGA) via ISB-CGC
BigQuery tables. RNA-seq expression values (TPM, hg38) were extracted for DDR1
across 2 cancer type(s) (KIRP, KIRC). Statistical analysis was performed using
wilcoxon_rank_sum with n=823 total samples.

GET /v1/cards/{card_id}/cite

curl https://api.bioquery.io/v1/cards/bq-2025-01-15-a7f3x/cite \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "bibtex": "@misc{bioquery_bq_2025_01_15_a7f3x,\n  author = {BioQuery},\n  title = {DDR1 Differential Expression - Query Card bq-2025-01-15-a7f3x},\n  year = {2025},\n  url = {https://bioquery.io/card/bq-2025-01-15-a7f3x}\n}",
  "apa": "BioQuery. (2025). DDR1 differential expression [Query Card bq-2025-01-15-a7f3x]. Retrieved from https://bioquery.io/card/bq-2025-01-15-a7f3x",
  "mla": "\"BioQuery: DDR1 Differential Expression.\" BioQuery, 2025, https://bioquery.io/card/bq-2025-01-15-a7f3x.",
  "url": "https://bioquery.io/card/bq-2025-01-15-a7f3x",
  "data_sources": [
    {
      "name": "TCGA",
      "citation": "The Cancer Genome Atlas Research Network. Comprehensive genomic characterization defines human glioblastoma genes and core pathways. Nature 455, 1061–1068 (2008).",
      "url": "https://www.cancer.gov/tcga"
    }
  ]
}

GET /v1/cards/{card_id}/context

{
  "projects": [
    {"project_id": "proj_123", "name": "DDR1 Research"}
  ],
  "explorations": [
    {"exploration_id": "exp_456", "name": "RCC Gene Analysis"}
  ],
  "studies": [
    {"study_id": "study_789", "title": "DDR1 as RCC Biomarker", "view_count": 142}
  ]
}

POST /v1/cards/{card_id}/fork

# Fork with a different gene
curl -X POST https://api.bioquery.io/v1/cards/bq-2025-01-15-a7f3x/fork \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gene": "DDR2"}'

{
  "new_card_id": "bq-2025-01-16-b8g4y",
  "parent_card_id": "bq-2025-01-15-a7f3x",
  "message": "Forked with modifications: gene=DDR2"
}

POST /v1/cards/{card_id}/rerun

curl -X POST https://api.bioquery.io/v1/cards/bq-2025-01-15-a7f3x/rerun \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "new_card_id": "bq-2025-01-16-c9h5z",
  "original_card_id": "bq-2025-01-15-a7f3x",
  "data_changed": true,
  "comparison": {
    "sample_count_change": {
      "original": 823,
      "new": 831,
      "delta": 8
    },
    "p_value_change": {
      "original": 0.00032,
      "new": 0.00028,
      "percent_change": 12.5
    }
  },
  "message": "Query re-executed with latest data - results have changed!"
}

GET /v1/cards/search

curl "https://api.bioquery.io/v1/cards/search?q=DDR1+kidney&gene=DDR1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "cards": [
    {
      "id": "bq-2025-01-15-a7f3x",
      "query": { "natural_language": "Is DDR1 higher in KIRP vs KIRC?" },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 3,
  "limit": 10,
  "offset": 0
}

GET /v1/cards

curl "https://api.bioquery.io/v1/cards?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "cards": [
    {
      "id": "card_abc123xyz",
      "query": "Is DDR1 higher in KIRP vs KIRC?",
      "created_at": "2024-01-15T10:30:00Z",
      "analysis_type": "differential_expression"
    },
    ...
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET /v1/data/cancer-types

{
  "cancer_types": [
    {
      "code": "BRCA",
      "name": "Breast invasive carcinoma",
      "sample_count": 1098
    },
    {
      "code": "LUAD",
      "name": "Lung adenocarcinoma",
      "sample_count": 533
    },
    ...
  ]
}

GET /v1/data/genes

curl "https://api.bioquery.io/v1/data/genes?search=DDR&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "genes": [
    {"symbol": "DDR1", "name": "Discoidin domain receptor tyrosine kinase 1"},
    {"symbol": "DDR2", "name": "Discoidin domain receptor tyrosine kinase 2"}
  ]
}

GET /v1/cards/{card_id}/export/{format}

# PNG export
curl "https://api.bioquery.io/v1/cards/card_abc123xyz/export/png?width=1200&height=800" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o figure.png
 
# SVG export
curl "https://api.bioquery.io/v1/cards/card_abc123xyz/export/svg" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o figure.svg