API Reference

LatticeZero provides a REST API for programmatic access to project management, target data, and scoring results. All compute (docking and scoring) runs client-side via WebGPU - the API handles data management and configuration.

Authentication

All API requests require authentication via session cookie or API key.

Session Authentication

When logged in via the web interface, your session cookie is automatically included in API requests.

API Key Authentication

For programmatic access, use an API key in the Authorization header:

Authorization: Bearer lz_your_api_key_here

API keys can be managed from your Account Settings page. See API Keys below.

Base URL

https://app.latticezero.com/api

All endpoints are prefixed with /api.

Endpoints

Projects

List Projects

GET /api/projects

Returns all projects for the authenticated user.

Response:

{
  "projects": [
    {
      "id": 42,
      "name": "Kinase Screening Campaign",
      "description": "CDK2 virtual screening",
      "created_at": "2026-01-15T10:30:00Z",
      "target_count": 3,
      "run_count": 12
    }
  ]
}

Get Project

GET /api/projects/<project_id>

Returns detailed project information including targets and recent runs.

Create Project

POST /api/projects
Content-Type: application/json

{
  "name": "My New Project",
  "description": "Optional description"
}

Targets

List Targets

GET /api/projects/<project_id>/targets

Returns all prepared targets in a project.

Get Target Details

GET /api/targets/<target_id>

Returns target metadata, grid statistics, and validation results.

Response:

{
  "id": 15,
  "name": "ACE_1O86",
  "pdb_id": "1O86",
  "target_class": "metalloprotease",
  "pocket_center": [34.2, 12.8, -5.1],
  "pocket_radius": 12.0,
  "grid_resolution": 0.375,
  "grid_points": 1048576,
  "validation_status": "passed",
  "created_at": "2026-01-15T11:00:00Z"
}

Scoring Runs

List Runs

GET /api/projects/<project_id>/runs

Returns all scoring runs in a project, with summary statistics.

Get Run Details

GET /api/runs/<run_id>

Returns full run details including per-ligand scores.

Response:

{
  "id": 128,
  "target_id": 15,
  "tool": "isoscore",
  "profile": "ace_platinum_v1",
  "status": "complete",
  "ligand_count": 1240,
  "duration_sec": 0.31,
  "created_at": "2026-01-15T14:22:00Z",
  "results": [
    {
      "ligand_name": "ACE_active_001",
      "rank": 1,
      "total_score": -42.8,
      "terms": {
        "E_disp": -18.3,
        "E_rep": 2.1,
        "E_coul": -12.4,
        "E_hbond": -8.2,
        "E_desolv": 1.5,
        "burial": -3.2,
        "strain": 0.8,
        "depth": -2.1,
        "aromaticBurial": -1.5,
        "hbondGeo": -0.9,
        "E_aromatic": -0.6,
        "contactArea": -1.2,
        "E_metal": -3.8,
        "E_clash": 0.0
      }
    }
  ]
}

Export Run Results

GET /api/runs/<run_id>/export?format=csv

Formats: csv, json, sdf

Returns the full results in the requested format as a file download.

Scoring Profiles

List Profiles

GET /api/profiles

Returns all available scoring profiles (built-in and custom).

Get Profile

GET /api/profiles/<profile_id>

Returns profile weights and metadata.

Response:

{
  "id": "ace_platinum_v1",
  "name": "ACE Platinum",
  "target_class": "metalloprotease",
  "tier": "platinum",
  "auc": 0.95,
  "weights": {
    "E_disp": 0.15,
    "E_rep": 0.08,
    "E_coul": 0.22,
    "E_hbond": 0.12,
    "E_desolv": 0.06,
    "burial": 0.10,
    "strain": 0.05,
    "depth": 0.04,
    "aromaticBurial": 0.02,
    "hbondGeo": 0.03,
    "E_aromatic": 0.02,
    "contactArea": 0.03,
    "E_metal": 0.18,
    "E_clash": 0.00
  }
}

Create Custom Profile

POST /api/profiles
Content-Type: application/json

{
  "name": "My Custom Profile",
  "target_class": "kinase",
  "weights": {
    "E_disp": 0.18,
    "E_rep": 0.10,
    ...
  }
}

PDB Fetch

Fetch from RCSB

GET /api/pdb/<pdb_id>

Fetches a PDB file from the RCSB Protein Data Bank.

Parameters:

• pdb_id - 4-character PDB identifier (e.g., 1AKE)

Response:

{
  "pdb_id": "1AKE",
  "title": "ADENYLATE KINASE",
  "resolution": 2.0,
  "organism": "Escherichia coli",
  "pdb_content": "HEADER    TRANSFERASE...",
  "ligands": ["AP5"]
}

API Keys

List Keys

GET /api/keys

Returns all API keys for the authenticated user (showing only prefix, not full key).

Create Key

POST /api/keys
Content-Type: application/json

{
  "label": "My CLI Script",
  "scopes": ["read", "write"]
}

Response (full key shown only once):

{
  "key": "lz_a1b2c3d4e5f6...",
  "key_prefix": "lz_a1b2",
  "label": "My CLI Script",
  "created_at": "2026-02-10T09:00:00Z"
}

Important: The full API key is only shown once at creation time. Store it securely.

Revoke Key

DELETE /api/keys/<key_id>

Permanently revokes an API key. This cannot be undone.

Rate Limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707561600

Error Handling

All errors follow a consistent format:

{
  "error": "not_found",
  "message": "Run with ID 999 not found",
  "status": 404
}

Common Error Codes

SDK & Examples

Python Example

import requests

API_KEY = "lz_your_key_here"
BASE = "https://app.latticezero.com/api"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List projects
projects = requests.get(f"{BASE}/projects", headers=headers).json()

# Get run results
run = requests.get(f"{BASE}/runs/128", headers=headers).json()

# Export as CSV
csv_data = requests.get(
    f"{BASE}/runs/128/export?format=csv",
    headers=headers
).text

cURL Example

# List profiles
curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/profiles

# Fetch PDB
curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/pdb/1AKE

REST API v1

The v1 API provides a versioned, stable interface for programmatic access to LatticeZero targets, profiles, and scoring. All v1 endpoints are prefixed with /api/v1/.

Base URL

https://app.latticezero.com/api/v1

Health Check

GET /api/v1/health

No authentication required. Returns service status and endpoint discovery.

cURL:

curl https://app.latticezero.com/api/v1/health

Response:

{
  "status": "healthy",
  "version": "0.9.7",
  "api_version": "v1",
  "endpoints": [
    "/api/v1/health",
    "/api/v1/targets",
    "/api/v1/targets/<target_id>",
    "/api/v1/profiles",
    "/api/v1/profiles/<profile_id>",
    "/api/v1/score"
  ]
}

List Targets

GET /api/v1/targets

Returns validated scoring targets with AUC metrics, tier, and target class.

Query Parameters:

cURL:

curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/v1/targets?tier=gold

Response:

{
  "targets": [
    {
      "id": "adrb2",
      "name": "ADRB2",
      "full_name": "Beta-2 Adrenergic Receptor",
      "target_class": "gpcr",
      "tier": "gold",
      "auc": 0.834,
      "dataset": "DEKOIS2",
      "score_mode": "hbq",
      "description": "GPCR with deep transmembrane pocket.",
      "supported_in_saas": true
    }
  ],
  "count": 3,
  "filters": {"tier": "gold", "target_class": null}
}

Get Target Details

GET /api/v1/targets/<target_id>

Returns detailed target info including scoring weights and key residues.

cURL:

curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/v1/targets/ace

Response:

{
  "id": "ace",
  "name": "ACE",
  "full_name": "Angiotensin-Converting Enzyme",
  "target_class": "metalloprotease",
  "tier": "silver",
  "auc": 0.596,
  "scoring_weights": {"E_coul": -0.5, "E_disp": 0.2},
  "key_residues": ["Zn", "GLU384", "HIS383", "HIS387"],
  "pocket_radius": 12.0,
  "reference_pdb": "1o86"
}

List Profiles

GET /api/v1/profiles

Same as targets but includes all profile variants (e.g., ace, ace_score_v1, ace_dock_v1).

Query Parameters: Same as /api/v1/targets.

cURL:

curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/v1/profiles?target_class=kinase

Get Profile Details

GET /api/v1/profiles/<profile_id>

Full profile detail with scoring weights dictionary.

cURL:

curl -H "Authorization: Bearer lz_your_key_here" \
  https://app.latticezero.com/api/v1/profiles/egfr

Score SMILES

POST /api/v1/score

Dock and score compounds against a target. Runs the full pipeline: SMILES → RDKit 3D → lz-dock → lz-score.

Requires API key with jobs:submit scope.

Request Body:

{
  "target_id": "ace",
  "smiles": ["CC(=O)Oc1ccccc1C(=O)O", "c1ccc(CC(=O)O)cc1"],
  "mode": "dock_score"
}

cURL:

curl -X POST \
  -H "Authorization: Bearer lz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"target_id":"ace","smiles":["CC(=O)Oc1ccccc1C(=O)O"]}' \
  https://app.latticezero.com/api/v1/score

Response:

{
  "status": "complete",
  "target_id": "ace",
  "mode": "dock_score",
  "input_count": 1,
  "scored_count": 1,
  "results": [
    {
      "ligand_id": "lig_0",
      "score": -28.4,
      "e_vdw": -15.2,
      "e_disp": -18.3,
      "e_rep": 3.1,
      "e_coul": -8.7,
      "e_hb": -4.5,
      "n_hbonds": 2
    }
  ]
}

Python SDK Example

import requests

API_KEY = "lz_your_key_here"
BASE = "https://app.latticezero.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Browse gold-tier targets
targets = requests.get(f"{BASE}/targets?tier=gold", headers=headers).json()
for t in targets["targets"]:
    print(f"{t['id']:12s}  AUC={t['auc']:.3f}  {t['target_class']}")

# Score a compound
resp = requests.post(f"{BASE}/score", headers=headers, json={
    "target_id": "ace",
    "smiles": ["CC(=O)Oc1ccccc1C(=O)O"]
}).json()

for r in resp["results"]:
    print(f"Score: {r['score']:.1f}  E_coul: {r['e_coul']:.1f}  H-bonds: {r['n_hbonds']}")