Skip to main content
IBBISIBBIS Screen

API Documentation

Integrate IBBIS Screen into your LIMS, synthesis pipeline, or bioinformatics workflows.

Getting Started

The IBBIS Screen API is a RESTful service that allows you to programmatically submit DNA/RNA sequences for biosecurity screening and retrieve the results. No authentication is required for the demo deployment.

Base URL
https://your-deployment.run.app/api/v1

Replace with your actual Cloud Run or local development URL.

Endpoints

POST

/api/v1/screen

Submit a new sequence for screening. Returns a job ID for polling.

curl -X POST https://your-deployment.run.app/api/v1/screen \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": ">GFP\nATGGTGAGCAAGGGCGAGGAG...",
    "name": "GFP Construct"
  }'
Response 201 Created
{
  "job_id": "job_m1x2y3z4",
  "status": "queued"
}
GET

/api/v1/screen/{job_id}

Poll for the status and results of a screening job. Poll every 2 seconds until status is complete or error.

Response (Completed)
{
  "job_id": "job_m1x2y3z4",
  "status": "complete",
  "result": {
    "overall": "FLAG",
    "steps": [
      { "id": "1", "name": "Biorisk Scan", "status": "complete", "duration": 1.5 },
      { "id": "2", "name": "Protein Taxonomy", "status": "skipped" },
      { "id": "3", "name": "Nucleotide Taxonomy", "status": "skipped" },
      { "id": "4", "name": "Low-Concern Check", "status": "complete", "duration": 1.1 }
    ],
    "regions": [
      {
        "start": 721,
        "end": 891,
        "type": "biorisk",
        "label": "Flagged region — matches biorisk HMM profile",
        "score": 0.94
      }
    ]
  }
}
GET

/api/v1/screen/{job_id}/report

Download the full screening report in JSON or HTML format.

# JSON report
curl https://your-deployment.run.app/api/v1/screen/job_m1x2y3z4/report?format=json

# HTML report (visual, Plotly-based)
curl https://your-deployment.run.app/api/v1/screen/job_m1x2y3z4/report?format=html

Data Model

Screening Result Statuses
PASS

No biorisk sequences detected. Sequence is cleared.

FLAG

Biorisk sequences detected. Requires manual review before order fulfillment.

WARNING

Potential concerns detected but below flag threshold. Review recommended.

ERROR

Screening could not be completed due to a processing error.

Region Types
biorisk

Region matches a known hazardous protein family (toxin, virulence factor, etc.) in the biorisk HMM database.

regulated

Region matches a regulated pathogen taxon (requires full taxonomy screening, Steps 2-3).

benign

Region cleared as low-concern (housekeeping gene, common lab protein, vaccine strain, etc.).

unknown

Region could not be classified. May require manual investigation.