Development

API Reference

Complete REST API documentation for the MinION pathogen screening pipeline.

Base URL

https://api.minion-pipeline.com/{environment}/

production: Production environment

staging: Staging environment

development: Development environment

Authentication

API Key Authentication

All requests require an API key in the header

# Include in request headers
x-api-key: YOUR_API_KEY

Obtaining an API Key:

Contact your administrator for API key generation
Store the key securely in environment variables
Never commit API keys to version control

Endpoints

POST

/workflows

Start Workflow

Start a new analysis workflow

Request Body

{
  "run_id": "RUN-2024-001",
  "bucket": "minion-data",
  "input_prefix": "runs/RUN-2024-001/fast5/",
  "config": {
    "phases": {
      "basecalling": {
        "enabled": true,
        "skip_duplex": false
      },
      "qc": {
        "enabled": true,
        "min_quality": 9
      },
      "host_removal": {
        "enabled": true,
        "reference": "sus_scrofa_11.1"
      },
      "pathogen_detection": {
        "enabled": true,
        "databases": ["kraken2", "rvdb", "pmda"]
      },
      "quantification": {
        "enabled": true,
        "spike_in": "PhiX174"
      },
      "reporting": {
        "enabled": true,
        "formats": ["pdf", "json"]
      }
    }
  }
}

Response (200 OK)

{
  "run_id": "RUN-2024-001",
  "workflow_id": "123456",
  "execution_arn": "arn:aws:states:...",
  "status": "STARTED",
  "estimated_duration_hours": 8.5
}

Example Request

curl -X POST https://api.minion-pipeline.com/production/workflows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "RUN-2024-001",
    "bucket": "minion-data",
    "input_prefix": "runs/RUN-2024-001/fast5/"
  }'

GET

/workflows/{workflow_id}

Get Workflow Status

Get the status of a workflow execution

Path Parameters

workflow_id - Unique workflow identifier

Response (200 OK)

{
  "workflow_id": "123456",
  "run_id": "RUN-2024-001",
  "status": "RUNNING",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "phases": [
    {
      "name": "basecalling",
      "status": "COMPLETED",
      "started_at": "2024-01-15T10:05:00Z",
      "completed_at": "2024-01-15T12:00:00Z"
    },
    {
      "name": "qc",
      "status": "COMPLETED",
      "started_at": "2024-01-15T12:05:00Z",
      "completed_at": "2024-01-15T12:30:00Z"
    },
    {
      "name": "host_removal",
      "status": "RUNNING",
      "started_at": "2024-01-15T12:35:00Z"
    }
  ],
  "metrics": {
    "basecalling": {
      "total_reads": 50000,
      "mean_quality": 10.5,
      "total_bases": 150000000
    }
  },
  "pathogens": []
}

Status Values

INITIATED

Created but not started

RUNNING

Currently executing

COMPLETED

Successfully completed

FAILED

Execution failed

GET

/workflows

List Workflows

List all workflow executions with optional filtering

Query Parameters

status - Filter by status (RUNNING, COMPLETED, FAILED)
run_id - Filter by run ID (partial match)
limit - Maximum results (default: 20, max: 100)
offset - Pagination offset
days - Get workflows from last N days (default: 7)

Example Request

curl -X GET "https://api.minion-pipeline.com/production/workflows?status=COMPLETED&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Response (200 OK)

{
  "workflows": [
    {
      "workflow_id": "123456",
      "run_id": "RUN-2024-001",
      "status": "COMPLETED",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T18:00:00Z",
      "phases_completed": 6,
      "error_count": 0,
      "has_pathogens": true,
      "duration_seconds": 28800
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

GET

/pathogens/{run_id}

Get Pathogen Results

Get pathogen detection results for a specific run

Path Parameters

run_id - Run identifier

Query Parameters

pmda_only - Show only PMDA 91 pathogens (default: false)
min_reads - Minimum read count threshold (default: 0)
include_quantification - Include absolute quantification (default: false)

Response (200 OK)

{
  "run_id": "RUN-2024-001",
  "workflow_id": "123456",
  "total_pathogens": 8,
  "pmda_pathogens_detected": 5,
  "pmda_compliance": {
    "total": 91,
    "detected": 5,
    "not_detected": 86,
    "detection_rate": 0.055,
    "detected_list": ["HEV", "PCV2", "SS", "EC", "CA"],
    "critical_detected": false
  },
  "perv_analysis": {
    "detected": false
  },
  "pathogens": [
    {
      "code": "PCV2",
      "name": "Porcine circovirus 2",
      "read_count": 1250,
      "confidence": 0.98,
      "method": "kraken2",
      "is_pmda": true,
      "risk_level": "MEDIUM",
      "quantification": {
        "copies_per_ml": 5.2e4,
        "log10_copies": 4.72,
        "ci_lower": 4.8e4,
        "ci_upper": 5.6e4
      }
    }
  ]
}

DELETE

/workflows/{workflow_id}

Stop Workflow

Stop a running workflow execution

Request Body (optional)

{
  "reason": "User requested termination"
}

Response (200 OK)

{
  "workflow_id": "123456",
  "status": "STOPPING",
  "message": "Workflow termination initiated"
}

GET

/reports/{run_id}

Get Report URLs

Get analysis report download URLs

Query Parameters

format - Report format (pdf, json, html)

Response (200 OK)

{
  "run_id": "RUN-2024-001",
  "reports": {
    "pdf": "https://s3.amazonaws.com/...",
    "json": "https://s3.amazonaws.com/...",
    "html": "https://s3.amazonaws.com/...",
    "checklist": "https://s3.amazonaws.com/..."
  },
  "expires_at": "2024-01-22T10:00:00Z"
}

Error Responses

Error Format

All error responses follow this format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "run_id",
      "issue": "Required field missing"
    }
  },
  "timestamp": "2024-01-15T10:00:00Z",
  "request_id": "abc123"
}

Error Codes

400
VALIDATION_ERROR
401
AUTHENTICATION_ERROR
403
AUTHORIZATION_ERROR
404
NOT_FOUND
429
RATE_LIMIT_EXCEEDED
500
INTERNAL_ERROR

Rate Limiting

Default limit: 100 requests/minute

Burst limit: 200 requests

Response Headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

SDK Examples

Python

example.pypython

import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://api.minion-pipeline.com/production'

headers = {'x-api-key': API_KEY}

# Start workflow
response = requests.post(
    f'{BASE_URL}/workflows',
    headers=headers,
    json={
        'run_id': 'RUN-2024-001',
        'bucket': 'minion-data',
        'input_prefix': 'runs/RUN-2024-001/fast5/'
    }
)

workflow = response.json()
print(f"Workflow started: {workflow['workflow_id']}")

# Check status
status = requests.get(
    f"{BASE_URL}/workflows/{workflow['workflow_id']}",
    headers=headers
).json()

print(f"Status: {status['status']}")

Node.js

example.jsjavascript

const axios = require('axios');

const API_KEY = 'your-api-key';
const BASE_URL = 'https://api.minion-pipeline.com/production';

const client = axios.create({
  baseURL: BASE_URL,
  headers: {'x-api-key': API_KEY}
});

// Start workflow
async function startWorkflow(runId, bucket, prefix) {
  const response = await client.post('/workflows', {
    run_id: runId,
    bucket: bucket,
    input_prefix: prefix
  });

  return response.data;
}

// Usage
startWorkflow('RUN-2024-001', 'minion-data', 'runs/RUN-2024-001/fast5/')
  .then(workflow => console.log(`Started: ${workflow.workflow_id}`))
  .catch(error => console.error(error));