API Reference

Complete REST API documentation for the OncologyAI platform

Base URL

https://oncology-ai.net/apiProduction

http://localhost:8000/apiDevelopment

FPGA Job Management

Submit and monitor FPGA-accelerated computation jobs

POST

/fpga/jobs

Submit a new job to the FPGA queue

Parameters

Name	Type	Required	Description
type	FPGAJobType	Required	Type of computation to run
name	string	Required	Human-readable job name
parameters	object	Required	Job-specific parameters
priority	integer	Optional	Queue priority (1-10, default: 5)

Request Body

{
  "type": "tumor_growth",
  "name": "Breast Cancer Simulation #42",
  "parameters": {
    "grid_size": 128,
    "iterations": 500,
    "proliferation_rate": 0.6,
    "death_rate": 0.15,
    "migration_rate": 0.25,
    "initial_tumor_size": 10
  },
  "priority": 7
}

Response

{
  "job_id": "fpga_job_abc123",
  "status": "queued",
  "position": 3,
  "estimated_wait": "2 minutes",
  "message": "Job submitted successfully"
}

GET

/fpga/jobs

List all jobs in the queue

Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status (queued, running, completed, failed)
limit	integer	Optional	Max results (default: 50)

Response

{
  "jobs": [
    {
      "id": "fpga_job_abc123",
      "name": "Breast Cancer Simulation #42",
      "type": "tumor_growth",
      "status": "running",
      "progress": 45,
      "submitted_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:31:00Z"
    },
    {
      "id": "fpga_job_def456",
      "name": "Drug Screening Panel",
      "type": "drug_screening",
      "status": "queued",
      "position": 1,
      "submitted_at": "2024-01-15T10:32:00Z"
    }
  ],
  "queue_size": 5,
  "fpga_status": "busy"
}

GET

/fpga/jobs/{job_id}

Get detailed status of a specific job

Parameters

Name	Type	Required	Description
job_id	string	Required	The job identifier

Response

{
  "id": "fpga_job_abc123",
  "name": "Breast Cancer Simulation #42",
  "type": "tumor_growth",
  "status": "completed",
  "progress": 100,
  "submitted_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:31:00Z",
  "completed_at": "2024-01-15T10:33:45Z",
  "execution_time_ms": 165000,
  "result": {
    "tumor_cells": 1847,
    "necrotic_cells": 423,
    "healthy_cells": 14114,
    "growth_rate": 0.73,
    "grid_state": [[1,1,2,2,...], ...]
  },
  "fpga_metrics": {
    "power_usage_watts": 2.3,
    "temperature_celsius": 52.1,
    "utilization_percent": 78.5
  }
}

GET

/fpga/status

Get current FPGA hardware status

Response

{
  "connected": true,
  "status": "busy",
  "current_job": "fpga_job_abc123",
  "queue_length": 3,
  "metrics": {
    "temperature": 52.1,
    "power_usage": 2.3,
    "utilization": 78.5,
    "memory_used_mb": 256
  },
  "hardware": {
    "board": "PYNQ-Z1",
    "chip": "xc7z020",
    "ddr_mb": 512,
    "overlay": "tumor_growth_v1.2"
  }
}

FPGAJobType Enum

Valid values for the job type parameter

tumor_growthCellular automaton tumor simulation

drug_screeningIC50/EC50 dose-response analysis

genomic_analysisMutation counting and variant detection

immunotherapyT-cell dynamics simulation

treatment_optimizationMulti-objective protocol optimization

Error Codes

Common API error responses

Code	Status	Description
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid authentication
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error, contact support
503	Service Unavailable	FPGA or database unavailable

Error Response Format

{
  "error": "Invalid job type",
  "code": "INVALID_JOB_TYPE",
  "details": {
    "provided": "invalid_type",
    "valid_types": ["tumor_growth", "drug_screening", ...]
  }
}

SDK Examples

Quick start code snippets

import requests

API_BASE = "https://oncology-ai.net/api"

# Submit an FPGA job
response = requests.post(f"{API_BASE}/fpga/jobs", json={
    "type": "tumor_growth",
    "name": "My Simulation",
    "parameters": {
        "grid_size": 128,
        "iterations": 500,
        "proliferation_rate": 0.6
    }
})

job = response.json()
print(f"Job submitted: {job['job_id']}")

# Poll for completion
import time
while True:
    status = requests.get(f"{API_BASE}/fpga/jobs/{job['job_id']}").json()
    if status['status'] == 'completed':
        print(f"Results: {status['result']}")
        break
    elif status['status'] == 'failed':
        print(f"Error: {status.get('error')}")
        break
    time.sleep(5)

Command Palette

API Reference

Parameters

Request Body

Response

Parameters

Response

Parameters

Response

Response

Error Response Format