API Reference

RESTful API for accessing Africa's largest medical imaging platform

Base URL: https://api.afribiobank.org/v1
Version: 1.0.0

Getting Started

  1. 1

    Sign up for an account

    Create a free account at afribiobank.org/pricing

  2. 2

    Generate API keys

    Navigate to Dashboard → API Keys and generate your authentication credentials

  3. 3

    Make your first request

    Start with authentication endpoint to obtain JWT token

Academic Tier

1,000

requests per hour

Professional Tier

10,000

requests per hour

Enterprise Tier

Unlimited

with custom SLA

Endpoints

Authentication

POST/api/v1/auth/login

Authenticate and receive JWT access token

Request

{
  "email": "researcher@institution.edu",
  "password": "your-secure-password"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": "usr_123456",
    "email": "researcher@institution.edu",
    "role": "researcher",
    "institution": "University of Lagos"
  }
}
POST/api/v1/auth/refresh

Refresh access token using refresh token

Request

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Datasets

GET/api/v1/datasets

List available datasets with filters

Request

GET /api/v1/datasets?modality=ct&disease=tuberculosis&limit=20

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

{
  "datasets": [
    {
      "id": "ds_tb_west_africa_2024",
      "name": "West Africa TB Chest X-Ray Collection",
      "description": "25,000 chest X-rays from Nigeria, Ghana, Senegal",
      "modality": "x-ray",
      "disease_focus": ["tuberculosis"],
      "institutions": 12,
      "image_count": 25000,
      "annotation_status": "complete",
      "access_level": "academic",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 234,
  "page": 1,
  "per_page": 20
}
GET/api/v1/datasets/{dataset_id}

Get detailed information about a specific dataset

Request

GET /api/v1/datasets/ds_tb_west_africa_2024

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

{
  "id": "ds_tb_west_africa_2024",
  "name": "West Africa TB Chest X-Ray Collection",
  "description": "25,000 chest X-rays from Nigeria, Ghana, Senegal...",
  "statistics": {
    "total_images": 25000,
    "positive_cases": 8750,
    "negative_cases": 16250,
    "age_range": "18-75",
    "gender_distribution": {"male": 0.52, "female": 0.48}
  },
  "institutions": [...],
  "citation": "Adeyemi et al. (2024). Lancet Digital Health...",
  "license": "CC-BY-NC-4.0",
  "download_url": "/api/v1/datasets/ds_tb_west_africa_2024/download"
}

Images

GET/api/v1/images/search

Search for specific medical images

Request

POST /api/v1/images/search

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body:
{
  "modality": "ct",
  "body_part": "brain",
  "disease": "glioblastoma",
  "age_range": [40, 70],
  "country": "KE",
  "annotated_only": true
}

Response

{
  "images": [
    {
      "id": "img_brain_001",
      "dataset_id": "ds_brain_tumors_ea",
      "modality": "ct",
      "body_part": "brain",
      "format": "dicom",
      "size_mb": 45.2,
      "dimensions": "512x512x120",
      "annotations": [
        {
          "type": "segmentation",
          "label": "tumor",
          "annotator": "radiologist_certified",
          "confidence": 0.98
        }
      ],
      "metadata": {
        "age": 54,
        "gender": "M",
        "acquisition_date": "2024-02-10",
        "institution": "Kenyatta National Hospital"
      },
      "download_url": "/api/v1/images/img_brain_001/download"
    }
  ],
  "total": 1247,
  "page": 1
}
GET/api/v1/images/{image_id}/download

Download a specific image file

Request

GET /api/v1/images/img_brain_001/download?format=nifti

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

Binary file download with appropriate Content-Type header
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="img_brain_001.nii.gz"

ML Models

GET/api/v1/models

List available pre-trained models

Request

GET /api/v1/models?task=classification&disease=tuberculosis

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

{
  "models": [
    {
      "id": "model_tb_classifier_v2",
      "name": "TB Detection - West Africa v2.0",
      "task": "classification",
      "disease": "tuberculosis",
      "modality": "x-ray",
      "accuracy": 0.95,
      "trained_on": "ds_tb_west_africa_2024",
      "framework": "pytorch",
      "deployment_status": "production",
      "api_endpoint": "/api/v1/models/model_tb_classifier_v2/predict"
    }
  ]
}
POST/api/v1/models/{model_id}/predict

Run inference on uploaded image

Request

POST /api/v1/models/model_tb_classifier_v2/predict

Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: multipart/form-data

Body:
image: <binary_file_upload>

Response

{
  "prediction": {
    "class": "tuberculosis_positive",
    "confidence": 0.94,
    "probabilities": {
      "tuberculosis_positive": 0.94,
      "normal": 0.04,
      "other_pathology": 0.02
    },
    "attention_map_url": "/results/attn_img_001.png",
    "processing_time_ms": 234
  },
  "model_version": "2.0.3",
  "disclaimer": "For research use only. Not for clinical diagnosis."
}

Official SDKs

Get started faster with our official client libraries