Working…
HTTP Integration Guide

PROTAC Builder API

Run PROTAC Builder workflows from your own scripts, notebooks, servers, or applications. Generate PROTAC-like structures, convert molecular formats, calculate RDKit descriptors, run DeepPK reports, and retrieve downloadable result files through simple HTTP requests.

REST API Python-ready RDKit descriptors DeepPK reports Batch workflows
Try the API Builder Open Web Builder Jump to Python Examples

Base URL

Choose the hosted domain for public integrations and the local address only for development.

Hosted API

https://protacbuilder.com

BASE_URL = "https://protacbuilder.com"

Local development

http://127.0.0.1:5069

BASE_URL = "http://127.0.0.1:5069"

curl -X POST http://127.0.0.1:5069/api/admet/run \
  -H "Content-Type: application/json" \
  -d '{"smiles":"CCO"}'

Quick Start

Typical order for script-driven molecular parameter workflows.

1
Generate or provide a PROTAC SMILES string. Use your own molecule, a generated PROTAC from POST /api/protac/generate, or a converted structure from the mapping endpoints below.
2
Call POST /api/admet/run first. This returns RDKit molecular descriptors quickly and is the fastest way to get immediate parameter output.
3
Call POST /api/deeppk/run second. DeepPK may take longer because it submits the molecule to the external prediction workflow and assembles the report files.
4
Download result files if they are returned. Successful DeepPK jobs may provide PDF, CSV, cleaned CSV, JSON, and SVG download links under the links object.
DeepPK failures are returned as structured JSON. RDKit descriptor calls and DeepPK report calls do not increment the PROTAC Builder usage counter.

Python Quick Start

Ready-to-run examples for notebooks, scripts, and backend jobs.

RDKit descriptors

import requests

BASE_URL = "https://protacbuilder.com"

response = requests.post(
    f"{BASE_URL}/api/admet/run",
    json={"smiles": "CCO"},
    timeout=60,
)

response.raise_for_status()
data = response.json()

print(data["descriptors"])

DeepPK report

import requests

BASE_URL = "https://protacbuilder.com"

response = requests.post(
    f"{BASE_URL}/api/deeppk/run",
    json={"smiles": "CCO"},
    timeout=300,
)

data = response.json()

if data.get("success"):
    print("DeepPK report ready")
    print(data.get("links") or data.get("deeppk"))
else:
    print("DeepPK failed")
    print(data.get("stage"))
    print(data.get("details"))

Download returned files

import requests
from pathlib import Path

BASE_URL = "https://protacbuilder.com"
links = data.get("links", {})

for label, url in links.items():
    file_response = requests.get(f"{BASE_URL}{url}", timeout=120)
    file_response.raise_for_status()
    Path(f"{label}_output").write_bytes(file_response.content)

Convert SMILES to MOL

import requests

BASE_URL = "https://protacbuilder.com"

response = requests.post(
    f"{BASE_URL}/api/molecule/smiles-to-mol",
    json={"smiles": "CCO"},
    timeout=60,
)

response.raise_for_status()
print(response.json())

End-to-End Examples

Practical client workflows built around the live API.

Python: RDKit first, then DeepPK

import requests

BASE_URL = "https://protacbuilder.com"
smiles = "CCO"

rdkit = requests.post(
    f"{BASE_URL}/api/admet/run",
    json={"smiles": smiles},
    timeout=60,
).json()

print("RDKit descriptors:")
print(rdkit.get("descriptors"))

deeppk = requests.post(
    f"{BASE_URL}/api/deeppk/run",
    json={"smiles": smiles},
    timeout=300,
).json()

if deeppk.get("success"):
    print("DeepPK files:")
    print(deeppk.get("links"))
else:
    print("DeepPK did not complete:")
    print(deeppk.get("details"))

Python: convert SMILES to MOL, then back to SMILES

import requests

BASE_URL = "https://protacbuilder.com"

mol_result = requests.post(
    f"{BASE_URL}/api/molecule/smiles-to-mol",
    json={"smiles": "CCO"},
    timeout=60,
).json()

smiles_result = requests.post(
    f"{BASE_URL}/api/molecule/mol-to-smiles",
    json={"mol": mol_result["mol"]},
    timeout=60,
).json()

print(smiles_result["smiles"])

Python: fetch curated linkers

import requests

BASE_URL = "https://protacbuilder.com"

linkers = requests.get(
    f"{BASE_URL}/api/linkers/curated",
    params={"page": 1, "sort_by": "Molecular Weight", "sort_order": "asc"},
    timeout=60,
).json()

print(linkers[0])

Python: download the batch template

import requests
from pathlib import Path

BASE_URL = "https://protacbuilder.com"

response = requests.get(
    f"{BASE_URL}/api/protac/builder/template/linkers",
    timeout=120,
)
response.raise_for_status()

Path("api_linkers_template.csv").write_bytes(response.content)

curl: RDKit descriptors (hosted)

curl -X POST https://protacbuilder.com/api/admet/run \
  -H "Content-Type: application/json" \
  -d '{"smiles":"CCO"}'

curl: DeepPK report (hosted)

curl -X POST https://protacbuilder.com/api/deeppk/run \
  -H "Content-Type: application/json" \
  -d '{"smiles":"CCO"}'

Molecular Parameters

Use RDKit for fast descriptors and DeepPK for report files and external prediction output.

Browser integrations should call /api/admet/run first, render descriptors immediately, then call /api/deeppk/run. That is the same sequence used by the Get Parameters button.
POST /api/admet/run RDKit descriptors

Fast local descriptor endpoint for SMILES or MOL input.

Request

{
  "smiles": "CCO"
}

Success

{
  "success": true,
  "descriptors": {
    "smiles": "CCO",
    "molecular_weight": 46.069,
    "exact_molecular_weight": 46.04186,
    "logp": -0.001,
    "tpsa": 20.23,
    "hbd": 1,
    "hba": 1,
    "qed": 0.4068,
    "lipinski_violations": 0
  },
  "warnings": []
}

Also accepts mol_block or molBlock. The response includes a properties alias and file links for JSON and CSV report exports.

POST /api/deeppk/run PDF + CSV + JSON

Runs the DeepPK workflow and prepares downloadable report artifacts.

Request

{
  "smiles": "CCO"
}

Success

{
  "success": true,
  "job_id": "20260519_123924_040e4d99",
  "links": {
    "pdf": "/api/deeppk/download/<job_id>/JARI_PROTAC_Report.pdf",
    "csv": "/api/deeppk/download/<job_id>/DeepPK_Predictions.csv",
    "cleaned_csv": "/api/deeppk/download/<job_id>/DeepPK_Cleaned_Output.csv",
    "json": "/api/deeppk/download/<job_id>/DeepPK_Predictions.json",
    "svg": "/api/deeppk/download/<job_id>/Protac.svg"
  }
}

Failure

{
  "success": false,
  "error": "DeepPK report generation failed.",
  "details": "Safe error message",
  "stage": "run_deeppk_display",
  "job_id": "20260519_123924_040e4d99",
  "rdkit_descriptors": {},
  "retryable": true
}

DeepPK responses also include rdkit_descriptors, a deeppk link alias, and warnings. Failures are structured JSON rather than HTML tracebacks.

GET /api/deeppk/download/<job_id>/<filename> File download

Downloads a DeepPK file created by a successful report job.

GET /api/deeppk/download/20260519_123924_040e4d99/JARI_PROTAC_Report.pdf
  • Success: binary file response with attachment headers.
  • Notes: filenames are the paths returned in the links object from /api/deeppk/run.
GET /api/admet/download/<filename> CSV or JSON file

Downloads files generated by the local RDKit descriptor workflow.

GET /api/admet/download/admet_report_20260519_123000.csv
  • Success: binary file response with attachment headers.
  • Notes: available filenames are returned by /api/admet/run under files.

Molecular Format Conversion

Helpers for moving between SMILES, MOL blocks, and rendered previews.

POST /api/molecule/smiles-to-mol

Convert a SMILES string into a MOL block.

Request

{
  "smiles": "CCO"
}

Success

{
  "success": true,
  "mol": "...",
  "mol_block": "..."
}
POST /api/molecule/mol-to-smiles

Convert a MOL block back to SMILES.

Request

{
  "mol": "..."
}

Success

{
  "success": true,
  "smiles": "CCO"
}

The endpoint accepts either mol or molBlock.

POST /api/molecule/render-smiles

Render a SMILES string to an inline preview image.

Request

{
  "smiles": "CCO"
}

Success

{
  "success": true,
  "image": "data:image/png;base64,..."
}

PROTAC Generation

Single-molecule generation plus multipart batch and ZIP workflows.

POST /api/protac/generate canonical generator

Generate a PROTAC MOL block from three prepared molecule blocks.

Request

{
  "warhead_mol": "...",
  "linker_mol": "...",
  "ligase_mol": "..."
}

Success

{
  "success": true,
  "protac_mol_block": "...",
  "protac_smiles": "..."
}

This endpoint increments the usage counter only when the build succeeds.

POST /api/protac/builder/batch multipart/form-data

Batch-build PROTAC SMILES from mapped warhead and ligase SMILES plus a linker CSV.

Fields:
warhead_smiles
ligase_smiles
linker_csv
smiles_col
name_col
source (optional)
{
  "count": 12,
  "failed": 1,
  "warnings": [],
  "message": "Built 12 PROTAC(s). Skipped 1 row(s).",
  "results": [{"name": "LINKER_1_PROTAC", "smiles": "..."}],
  "failures": [{"row": 6, "reason": "..."}]
}
POST /api/protac/builder/cli ZIP output

Advanced multipart endpoint for command-line style batch execution.

Fields:
target
ligase
library
source (optional)
  • Success: application/zip download containing results, failure CSV, and run log.
  • Notes: useful for external batch jobs that want a single bundle instead of JSON rows.
POST /api/protac/batch-linkers multipart/form-data

Build PROTAC products from warhead and ligase molecule blocks plus a linker CSV.

Fields:
warhead_mol
ligase_mol
linker_csv
{
  "count": 4,
  "results": [{"name": "LINKER_1_PROTAC", "smiles": "..."}]
}

Linker and Recruiter Data

Catalog lookups, raw molecule access, and rendered previews for script-driven discovery work.

GET /api/linkers/curated

Fetch curated linker records with paging and sort options.

GET /api/linkers/curated?page=1&sort_by=Molecular%20Weight&sort_order=asc
[
  {
    "id": 462,
    "smiles": "C",
    "molecular_weight": 16.043,
    "svg": "<svg ...>"
  }
]
GET /api/ligases

Return the available ligase names.

["CRBN_EF2", "VHL_3JF", "..."]
GET /api/ligase/render

Return a ligase preview for the requested name.

GET /api/ligase/render?ligase=VHL_3JF
{
  "mol_block": "...",
  "image": "data:image/svg+xml;base64,..."
}
GET /api/ligase/raw/<name>

Fetch the raw MOL block for a ligase entry.

{
  "mol_block": "..."
}
GET /api/recruiter/<name>

Load recruiter molecule data by recruiter identifier.

{
  "name": "VHL_VH032",
  "smiles": "...",
  "mol_block": "..."
}
GET /api/ligand/smiles

Get the stored SMILES for a ligand identifier.

GET /api/ligand/smiles?ligand=DR7
{
  "smiles": "..."
}
GET /api/ligand/data

Get the ligand identifier, SMILES, and MOL block in one response.

GET /api/ligand/data?ligand=DR7
{
  "ligand": "DR7",
  "smiles": "...",
  "mol_block": "..."
}

Ligand Editing Utilities

Small helper routes used by custom editors or notebook-driven curation tasks.

POST /api/ligand/modify

Normalize a ligand SMILES string and return both SMILES and MOL block output.

{
  "smiles": "CCO"
}
{
  "mol_block": "...",
  "smiles": "CCO"
}
POST /api/ligand/store

Store ligand metadata from an external workflow.

{
  "ligand": "DR7",
  "smiles": "CCO"
}
{
  "message": "Ligand DR7 stored successfully!"
}

Structure Mapping Utilities

Use these endpoints when your client needs mapping, uploads, or linker CSV inspection before generation.

POST /api/protac/structure/convert multipart/form-data

Convert an uploaded structure file or a form SMILES string into a MOL block.

Fields:
smiles
or
structure_file
{
  "mol_block": "...",
  "smiles": "..."
}
POST /api/protac/structure/mapped-smiles

Generate mapped attachment-point SMILES from a MOL block.

{
  "molBlock": "..."
}
{
  "smiles": "[*:1]CCO",
  "warnings": []
}
POST /api/protac/linkers/inspect multipart/form-data

Inspect a linker CSV and detect useful column names before batch generation.

Fields:
linker_csv
or
file
{
  "columns": ["name", "smiles"],
  "preview_rows": [{"name": "L1", "smiles": "[*:1]CC[*:2]"}],
  "suggested_smiles_col": "smiles",
  "suggested_name_col": "name"
}

Operations

Health, templates, usage metrics, and advanced job lookups.

GET /api/protac/builder/usage verified counter

Returns the current PROTAC Builder usage summary.

{
  "seed_total": 127,
  "local_actions": 5,
  "total": 132,
  "canonical_log_file": "...",
  "counting_rule": "successful generated PROTAC builds only"
}

Only successful PROTAC generation increments this counter.

GET /api/protac/builder/template/linkers

Download the CSV template used by the batch builder workflow.

GET /api/protac/builder/template/linkers
  • Success: CSV file download.
GET /api/protac/builder/template/download-count

Read the number of recorded template downloads.

{
  "downloads": 14
}
GET /api/warheadhunter/job/<job_id> advanced endpoint

Lookup route for Warhead Hunter job artifacts when that workflow is present in the deployment.

  • Notes: useful as an available endpoint for deployments that expose Warhead Hunter job output.
GET /healthz

Simple health check for monitoring and local startup checks.

{
  "ok": true
}

Frontend Get Parameters Flow

Reference sequence for client-side integrations that mirror the web builder.

  1. User clicks Get Parameters.
  2. Browser extracts the current generated PROTAC SMILES.
  3. Browser calls /api/admet/run.
  4. RDKit Molecular Parameters render immediately.
  5. Browser calls /api/deeppk/run.
  6. An inline loader appears with rotating progress messages.
  7. On DeepPK success, download buttons appear.
  8. On DeepPK failure, the RDKit table stays visible and an inline error card appears.
  • No browser alert() should be used for DeepPK failures.
  • DeepPK failures should not erase the RDKit descriptor output.
  • DeepPK report requests should not increment the PROTAC Builder usage counter.
  • Only successful PROTAC generation should increment usage.
  • The interactive API Builder is available if you want a no-code companion while testing payloads.