API Reference

Programmatic access to the ECOD domain classification database. All endpoints return JSON and are publicly accessible with CORS enabled.

Overview

Base URLhttps://prodata.swmed.edu/ecod2/api/v1

FormatJSON (application/json)

AuthNone required. All endpoints are public.

Rate Limit100 requests per minute per IP address. Returns HTTP 429 with Retry-After header when exceeded.

CORSEnabled for all origins. Safe to call from browser JavaScript.

Endpoints

GET /api/v1/health — Service health check
GET /api/v1/domains/:uid — Domain details by UID
GET /api/v1/domains/:uid/pdb — Domain PDB coordinates
GET /api/v1/domains/:uid/fasta — Domain FASTA sequence
GET /api/v1/domains/uniprot/:acc — Domains by UniProt accession
GET /api/v1/domains/pdb/:pdbId — Domains by PDB entry
GET /api/v1/domains/pfam/:acc — Domains by Pfam accession
GET /api/v1/domains/clan/:acc — Domains by Pfam clan
GET /api/v1/domains/unclassified/:groupId — Unclassified domains in an ECOD group

Health Check

GET/api/v1/health

Returns service status and database connectivity. Returns HTTP 503 if the database is unreachable.

Example Response

{
  "status": "ok",
  "version": "1.0.0",
  "database": "connected",
  "latency_ms": 22
}

Try It

Get Domain

GET/api/v1/domains/:uid

Retrieve a single domain by its numeric UID, including full classification hierarchy and links to downloadable files.

Parameters

uidintegerrequired— Domain unique identifier (0 or greater)

Example Response

{
  "uid": 2083261,
  "ecod_domain_id": "e2nmzA1",
  "type": "experimental structure",
  "source_id": "2nmz_A",
  "uniprot_acc": "P00519",
  "chain_id": "A",
  "range": "242-502",
  "classification": {
    "architecture": "beta barrels",
    "x_group": "Cradle loop barrel",
    "h_group": "Protein kinase-like (PK-like)",
    "t_group": "Protein kinase-like (PK-like)",
    "family": "Protein kinases, catalytic subunit"
  },
  "is_representative": false,
  "is_manual": true,
  "files": {
    "pdb": "/api/v1/domains/2083261/pdb",
    "fasta": "/api/v1/domains/2083261/fasta"
  }
}

Try It

Download Domain PDB

GET/api/v1/domains/:uid/pdb

Download pre-cut PDB coordinates for a domain. Returns the atomic coordinates for just the domain residues extracted from the parent structure. Content-Type: chemical/x-pdb.

Parameters

uidintegerrequired— Domain unique identifier

Example Response

HEADER    ecod_002083261
ATOM      1  N   GLU A 242      34.662  28.228  52.640  1.00 38.22           N
ATOM      2  CA  GLU A 242      34.434  29.524  52.000  1.00 37.63           C
...

Try It

Download Domain FASTA

GET/api/v1/domains/:uid/fasta

Download FASTA-format protein sequence for a domain. Content-Type: text/plain.

Parameters

uidintegerrequired— Domain unique identifier

Example Response

>ecod_002083261 e2nmzA1 242-502
EEALQRPVASDFEPQGLSEAARWNSKENLLAGPSENDPNL...

Try It

Domains by UniProt

GET/api/v1/domains/uniprot/:acc

Retrieve all ECOD domains associated with a UniProt accession. Returns both experimental and AlphaFold domains.

Parameters

accstringrequired— UniProt accession (e.g., P00519)

Example Response

{
  "uniprot_acc": "P00519",
  "domain_count": 138,
  "domains": [
    {
      "uid": 2083261,
      "ecod_domain_id": "e2nmzA1",
      "type": "experimental structure",
      "source_id": "2nmz_A",
      "chain_id": "A",
      "range": "242-502",
      "classification": {
        "architecture": "beta barrels",
        "x_group": "Cradle loop barrel",
        "h_group": "Protein kinase-like (PK-like)",
        "t_group": "Protein kinase-like (PK-like)",
        "family": "Protein kinases, catalytic subunit"
      },
      "is_representative": false,
      "is_manual": true
    }
  ]
}

Try It

Domains by PDB

GET/api/v1/domains/pdb/:pdbId

Retrieve all ECOD domains from a PDB entry. The PDB ID is case-insensitive.

Parameters

pdbIdstringrequired— PDB identifier (e.g., 2nmz)

Example Response

{
  "pdb_id": "2nmz",
  "domain_count": 2,
  "domains": [
    {
      "uid": 2083261,
      "ecod_domain_id": "e2nmzA1",
      "type": "experimental structure",
      "source_id": "2nmz_A",
      "chain_id": "A",
      "range": "242-502",
      "classification": {
        "architecture": "beta barrels",
        "x_group": "Cradle loop barrel",
        "h_group": "Protein kinase-like (PK-like)",
        "t_group": "Protein kinase-like (PK-like)",
        "family": "Protein kinases, catalytic subunit"
      },
      "is_representative": false,
      "is_manual": true
    }
  ]
}

Try It

Domains by Pfam

GET/api/v1/domains/pfam/:acc

Retrieve all ECOD domains in F-groups mapped to a Pfam accession. Includes Pfam metadata, clan membership, and the list of matching ECOD F-groups.

Parameters

accstringrequired— Pfam accession (e.g., PF00077)

Example Response

{
  "pfam_acc": "PF00077",
  "pfam_id": "Toxin_1",
  "pfam_description": "Scorpion short toxin, BmKa1",
  "clan": { "acc": "CL0054", "name": "Knottin_1" },
  "fgroup_count": 2,
  "fgroups": [
    { "id": "6.1.1.4", "name": "Scorpion short toxin" }
  ],
  "domain_count": 245,
  "domains": [
    {
      "uid": 2083261,
      "ecod_domain_id": "e2nmzA1",
      "type": "experimental structure",
      "classification": { ... }
    }
  ]
}

Try It

Domains by Pfam Clan

GET/api/v1/domains/clan/:acc

Retrieve all ECOD domains mapped to any Pfam family within a clan. Returns the clan's member Pfam families, matching ECOD F-groups, and all associated domains.

Parameters

accstringrequired— Pfam clan accession (e.g., CL0054)

Example Response

{
  "clan_acc": "CL0054",
  "clan_name": "Knottin_1",
  "pfam_count": 38,
  "pfam_families": [
    { "acc": "PF00077", "id": "Toxin_1", "description": "Scorpion short toxin" },
    { "acc": "PF07740", "id": "Toxin_2", "description": "Scorpion short toxin" }
  ],
  "fgroup_count": 15,
  "fgroups": [
    { "id": "6.1.1.4", "name": "Scorpion short toxin" }
  ],
  "domain_count": 1832,
  "domains": [ ... ]
}

Try It

Unclassified Domains

GET/api/v1/domains/unclassified/:groupId

Retrieve domains within an ECOD group that are unclassified — in placeholder .0 families or families with no Pfam mapping. Works at any hierarchy level (X, H, T, or F group).

Parameters

groupIdstringrequired— ECOD group ID, dot-separated (e.g., 1 for X-group, 1.1 for H-group)

pageinteger— Page number (default: 1)

limitinteger— Results per page, max 1000 (default: 100)

no_pfam_onlyboolean— If true, only return domains in families with no Pfam mapping (excludes .0 filter)

Example Response

{
  "group_id": "1.1",
  "group_level": "H-group",
  "filter": "unclassified",
  "filter_description": "Domains in .0 (placeholder) F-groups or F-groups with no Pfam mapping",
  "unclassified_fgroup_count": 3,
  "unclassified_fgroups": [
    { "id": "1.1.1.0", "name": "Unclassified", "pfam_acc": null },
    { "id": "1.1.4.0", "name": "Unclassified", "pfam_acc": null }
  ],
  "domain_count": 487,
  "page": 1,
  "page_size": 100,
  "total_pages": 5,
  "domains": [ ... ]
}

Try It

Error Responses

All errors return a JSON object with an error field.

Status	Meaning	Example
400	Invalid parameter	{"error": "Invalid UID"}
404	Resource not found	{"error": "Domain not found"}
429	Rate limit exceeded	{"error": "Too many requests..."}
500	Server error	{"error": "Failed to fetch domain"}
503	Database unavailable	{"status": "degraded", ...}

Code Examples

Python

python

import requests

BASE = "https://prodata.swmed.edu/ecod2/api/v1"

# Get all domains for a UniProt accession
resp = requests.get(f"{BASE}/domains/uniprot/P00519")
data = resp.json()
print(f"Found {data['domain_count']} domains")

for d in data["domains"]:
    print(f"  {d['ecod_domain_id']}  {d['range']}  {d['classification']['family']}")

# Download a domain PDB file
pdb = requests.get(f"{BASE}/domains/2083261/pdb")
with open("ecod_2083261.pdb", "w") as f:
    f.write(pdb.text)

# Find all domains mapped to a Pfam family
resp = requests.get(f"{BASE}/domains/pfam/PF00077")
data = resp.json()
print(f"PF00077 ({data['pfam_id']}): {data['domain_count']} domains in {data['fgroup_count']} F-groups")

# Find all domains in a Pfam clan
resp = requests.get(f"{BASE}/domains/clan/CL0054")
data = resp.json()
print(f"Clan {data['clan_name']}: {data['pfam_count']} Pfam families, {data['domain_count']} domains")

# Get unclassified domains in an H-group (paginated)
resp = requests.get(f"{BASE}/domains/unclassified/1.1", params={"limit": 50})
data = resp.json()
print(f"{data['domain_count']} unclassified domains in {data['unclassified_fgroup_count']} F-groups")

JavaScript / Node.js

javascript

const BASE = "https://prodata.swmed.edu/ecod2/api/v1";

// Get domain details
const resp = await fetch(`${BASE}/domains/2083261`);
const domain = await resp.json();
console.log(domain.classification.family);
// => "Protein kinases, catalytic subunit"

// Get all domains for a UniProt accession
const unp = await fetch(`${BASE}/domains/uniprot/P00519`);
const { domains } = await unp.json();
console.log(`Found ${domains.length} domains`);

// Download FASTA
const fasta = await fetch(`${BASE}/domains/2083261/fasta`);
console.log(await fasta.text());

curl

bash

# Domain details
curl https://prodata.swmed.edu/ecod2/api/v1/domains/2083261

# All domains for a PDB entry
curl https://prodata.swmed.edu/ecod2/api/v1/domains/pdb/2nmz

# Download domain PDB file
curl -o ecod_2083261.pdb https://prodata.swmed.edu/ecod2/api/v1/domains/2083261/pdb

# All domains for a UniProt accession
curl https://prodata.swmed.edu/ecod2/api/v1/domains/uniprot/P00519

# Domains mapped to a Pfam family
curl https://prodata.swmed.edu/ecod2/api/v1/domains/pfam/PF00077

# Domains in a Pfam clan
curl https://prodata.swmed.edu/ecod2/api/v1/domains/clan/CL0054

# Unclassified domains in X-group 1 (page 1, 50 per page)
curl "https://prodata.swmed.edu/ecod2/api/v1/domains/unclassified/1?limit=50"

# Health check
curl https://prodata.swmed.edu/ecod2/api/v1/health

Questions about the API? Contact ecod.database@gmail.com. For bulk data downloads, see the distribution page.