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