API Reference

Build BSgenome packages programmatically. The public API does not require user authentication; user-triggered build artifacts are temporary and permanent repository inclusion is maintainer-curated.

Base URL: https://autobsgenome-api.bioinfoark.workers.dev

POST/api/build

Trigger a new BSgenome package build from NCBI, Ensembl, a FASTA URL, or an uploaded FASTA file.

Request Body

{
  "package_name": "BSgenome.Hsapiens.NCBI.GRCh38",
  "organism": "Homo sapiens",
  "common_name": "human",
  "genome": "GRCh38",
  "provider": "NCBI",
  "version": "1.0.0",
  "circ_seqs": "MT",
  "accession": "GCF_000001405.40",
  "data_source": "ncbi",
  "release_date": "2022-02-03",
  "source_url": "https://www.ncbi.nlm.nih.gov/datasets/genome/GCF_000001405.40/"
}

For FASTA URL builds, set fasta_source to url and include fasta_url. For browser uploads, set fasta_source to upload and include the signed fasta_upload_url returned by POST /api/uploads.

Response

{
  "job_id": "4c1e14f7",
  "status": "queued",
  "queue_position": 0,
  "delete_token": "hmac-token-for-this-job"
}

Keep delete_token private. It can delete the temporary GitHub Release for this job before the scheduled two-day cleanup.

GET/api/status/:jobId

Check build status. Poll every 5-10 seconds. When GitHub Actions metadata is available, the response includes live step timings.

Response (building)

{
  "job_id": "4c1e14f7",
  "status": "building",
  "build_steps": [
    { "key": "queue", "label": "Queuing build on GitHub Actions", "status": "complete", "seconds": 4 },
    { "key": "download", "label": "Downloading FASTA", "status": "running", "seconds": 18 },
    { "key": "twobit", "label": "Converting to 2bit format", "status": "pending" }
  ],
  "workflow_run_url": "https://github.com/.../actions/runs/123456789"
}

Response (complete)

{
  "job_id": "4c1e14f7",
  "status": "complete",
  "package_name": "BSgenome.Hsapiens.NCBI.GRCh38 1.0.0",
  "download_url": "https://github.com/.../BSgenome.Hsapiens.NCBI.GRCh38_1.0.0.tar.gz",
  "file_name": "BSgenome.Hsapiens.NCBI.GRCh38_1.0.0.tar.gz",
  "file_size": 782000000,
  "published": false,
  "total_seconds": 226
}

Response (failed)

{
  "job_id": "4c1e14f7",
  "status": "failed",
  "message": "BUILD_FAILED: Downloading FASTA failed. Check the linked GitHub Actions run for detailed logs.",
  "workflow_run_url": "https://github.com/.../actions/runs/123456789"
}

GET/api/queue

Check current GitHub Actions queue depth.

{
  "running": 1,
  "queued": 2,
  "total": 3,
  "max_queue": 10,
  "runs": [
    { "id": 123, "status": "running", "name": "Build BSgenome.Xxx (...)", "created_at": "2026-07-01T12:00:00Z" }
  ]
}

DELETE/api/build/:jobId

Delete a temporary build-<jobId> release and tag. This only applies to temporary build downloads.

{
  "delete_token": "hmac-token-from-post-build"
}

{
  "status": "deleted",
  "job_id": "4c1e14f7",
  "release_deleted": true,
  "tag_deleted": true
}

POST/api/uploads

Create a multipart upload session for a local nucleotide FASTA file. Uploads are staged in private R2 storage and expire after two days.

{
  "file_name": "my-genome.fasta.gz",
  "file_size": 73400320,
  "content_type": "application/gzip"
}

{
  "upload_id": "9ccfb9e2-0ab9-4a23-a9de-6f8fd4c67c0a",
  "part_size": 67108864,
  "part_url_template": "https://autobsgenome-api.bioinfoark.workers.dev/api/uploads/.../parts/{part_number}?...",
  "complete_url": "https://autobsgenome-api.bioinfoark.workers.dev/api/uploads/.../complete?...",
  "download_url": "https://autobsgenome-api.bioinfoark.workers.dev/api/uploads/...",
  "delete_url": "https://autobsgenome-api.bioinfoark.workers.dev/api/uploads/...",
  "expires_at": "2026-07-03T12:00:00.000Z",
  "max_upload_bytes": 4294967296
}

Supported filenames end in .fa, .fasta, .fna, or .fas, optionally with .gz. Protein FASTA extensions such as .faa, .pep, and .aa are rejected. Maximum browser upload size is 4 GB.

Examples

curl (bash)

# 1. Trigger build
JOB=$(curl -s -X POST https://autobsgenome-api.bioinfoark.workers.dev/api/build \
  -H "Content-Type: application/json" \
  -d '{"package_name":"BSgenome.Scerevisiae.NCBI.R64","organism":"Saccharomyces cerevisiae","genome":"R64","provider":"NCBI","version":"1.0.0","accession":"GCF_000146045.2","data_source":"ncbi","circ_seqs":"MT"}')
JOB_ID=$(echo "$JOB" | python3 -c "import json,sys; print(json.load(sys.stdin)['job_id'])")
DELETE_TOKEN=$(echo "$JOB" | python3 -c "import json,sys; print(json.load(sys.stdin)['delete_token'])")

# 2. Poll for completion
while true; do
  STATUS=$(curl -s "https://autobsgenome-api.bioinfoark.workers.dev/api/status/$JOB_ID")
  echo "$STATUS"
  echo "$STATUS" | python3 -c "import json,sys; s=json.load(sys.stdin)['status']; exit(0 if s in ('complete','failed') else 1)" && break
  sleep 10
done

# 3. Install in R when complete
URL=$(echo "$STATUS" | python3 -c "import json,sys; print(json.load(sys.stdin).get('download_url',''))")
Rscript -e "local({options(timeout = 7200); url <- '$URL'; tarball <- tempfile(fileext = '.tar.gz'); on.exit(unlink(tarball), add = TRUE); download.file(url, tarball, mode = 'wb', method = 'libcurl'); install.packages(tarball, repos = NULL, type = 'source')})"

# Optional: delete the temporary public release early
curl -X DELETE "https://autobsgenome-api.bioinfoark.workers.dev/api/build/$JOB_ID" \
  -H "Content-Type: application/json" \
  -d "{\"delete_token\":\"$DELETE_TOKEN\"}"

R install command

local({options(timeout = 7200); url <- "TARBALL_URL_FROM_STATUS_OR_PACKAGE_CARD"; tarball <- tempfile(fileext = ".tar.gz"); on.exit(unlink(tarball), add = TRUE); download.file(url, tarball, mode = "wb", method = "libcurl"); install.packages(tarball, repos = NULL, type = "source")})

Limits & Notes

Build requests are queued through GitHub Actions.
Status responses include live step timings when GitHub run metadata is available.
Temporary build releases are automatically cleaned up after two days.
Users can delete their current temporary build earlier with the returned delete_token.
Permanent package repository inclusion is curated by maintainers and is not available through the public API.
CORS is enabled for the AutoBSgenome site, staging Workers, preview deployments, and localhost development.