Endpoints
The Folding API provides several categories of endpoints:
Core Folding Endpoints
Fold with the Bittensor network using a PDB ID from RCSB or PDBE.
This endpoint is for folding proteins that are already available in the RCSB or PDBE databases. The PDB ID must be specified in the query parameters.
Represents a request to a validator.
The PDB identifier for the selected response source.
1ubqThe source of the folding request from two recognized databases.
rcsbPossible values: The force field for the selected response source.
charmm36.xmlThe water model for the selected response source.
charmm36/water.xmlThe box type for the selected response source.
The temperature for the selected response source.
The friction coefficient for the selected response source.
The base epsilon that should be used for the challenge. Represented in %/100
The validator identifier for the selected response source.
The time to live for the job in seconds.
The number of validators to sample.
The time in seconds to wait for a response.
5POST /fold HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 215
{
"pdb_id": "1ubq",
"source": "rcsb",
"ff": "charmm36.xml",
"water": "charmm36/water.xml",
"box": "cube",
"temperature": 1,
"friction": 1,
"epsilon": 1,
"validator_uids": [
1
],
"time_to_live": 1,
"num_validators_to_sample": 1,
"timeout": 5
}{
"uids": [
1
],
"hotkeys": [
"text"
],
"status_codes": [
null
],
"job_id": [
"text"
]
}Fold with the Bittensor network using a custom PDB file.
This endpoint is for folding proteins using a custom PDB file that you provide. The file must be uploaded as part of the request.
POST /fold/upload HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 36
{
"pdb_file": "binary",
"query": "text"
}{
"uids": [
1
],
"hotkeys": [
"text"
],
"status_codes": [
null
],
"job_id": [
"text"
]
}API Key Management
Create a new API key (admin only)
100/hourPOST /api-keys HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"owner": "text",
"rate_limit": "100/hour"
}{
"owner": "text",
"rate_limit": "text",
"is_active": true,
"key": "text"
}Utility Endpoints
Search for PDB IDs in the database.
This endpoint searches through the pdb_ids.pkl file and returns a list of matching PDB IDs. The search uses simple substring matching to find PDB IDs that contain the query string. Results are sorted by position of the match (matches at the beginning rank higher).
Each PDB ID is returned with its source (rcsb or pdbe). Supports pagination through page and page_size parameters.
Search query for PDB IDs
Page number to return (1-based)
1Number of results per page
100GET /search?query=text HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
{
"matches": [
{
"pdb_id": "text",
"source": "text"
}
],
"total": 1
}Retrieve detailed information about a PDB structure from RCSB.
This endpoint queries the RCSB PDB GraphQL API to get information about a specific PDB entry.
GET /pdb/{pdb_id} HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
{
"pdb_id": "text",
"molecule_name": "text",
"classification": "text",
"organism": "text",
"expression_system": "text"
}Retrieve the PDB file for a given PDB ID. First checks the S3 bucket, if not found falls back to RCSB or PDBe sources.
The source of the PDB file to download
GET /pdb/{pdb_id}/file?input_source=null HTTP/1.1
Host:
Accept: */*
No content
Retrieve PDB structure image URLs from S3 bucket. Returns URLs for both small (200px) and large (800px) versions of the image.
GET /pdb/{pdb_id}/images HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
No content
Retrieve the status of the job pool.
Filter jobs by their status and optionally by specific job IDs. Search for jobs with specific PDB IDs using substring matching. Supports pagination through page and page_size parameters.
List of specific job IDs to filter by
Search query for PDB IDs
Page number to return (1-based)
1Number of results per page
100GET /job_pool?status=active HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
{
"jobs": [
{
"id": "text",
"type": "organic",
"job_id": "text",
"pdb_id": "text",
"created_at": "text",
"status": "active",
"priority": 1,
"validator_hotkey": "text",
"best_hotkey": "text",
"s3_links": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"total": 1
}Retrieve a specific job by its ID.
Whether to return mock miner data instead of real data
falseGET /job_pool/{job_id} HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
{
"pdb_id": "text",
"pdb_data": "text",
"pdb_file_link": "text",
"organism": "text",
"classification": "text",
"expression_system": "text",
"mutations": true,
"source": "text",
"temperature": 1,
"friction": 1,
"pressure": 1,
"time_to_live": 1,
"ff": "text",
"water": "text",
"box": "text",
"miners": [
{
"uid": "text",
"hotkey": "text",
"energy": [
{
"ANY_ADDITIONAL_PROPERTY": 1
}
],
"final_energy": 1
}
],
"status": "inactive",
"created_at": "",
"updated_at": ""
}Last updated