Endpoints

The Folding API provides several categories of endpoints:

Core Folding Endpoints

Fold

post

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.

Authorizations

Body

Represents a request to a validator.

pdb_idstringOptional

The PDB identifier for the selected response source.

Default: 1ubq

sourcestring · enumOptional

The source of the folding request from two recognized databases.

Default: rcsbPossible values:

ffstringOptional

The force field for the selected response source.

Default: charmm36.xml

waterstringOptional

The water model for the selected response source.

Default: charmm36/water.xml

boxstring · enumRequired

The box type for the selected response source.

Possible values:

temperaturenumberRequired

The temperature for the selected response source.

frictionnumberRequired

The friction coefficient for the selected response source.

epsilonnumberRequired

The base epsilon that should be used for the challenge. Represented in %/100

validator_uidsinteger[]Required

The validator identifier for the selected response source.

time_to_liveany ofOptional

The time to live for the job in seconds.

integerOptional

or

nullOptional

num_validators_to_sampleany ofOptional

The number of validators to sample.

integerOptional

or

nullOptional

timeoutintegerOptional

The time in seconds to wait for a response.

Default: 5

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /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 Upload

post

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.

Authorizations

Body

pdb_filestring · binaryRequired

querystringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

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

List Api Keys

get

List all API keys (admin only)

Authorizations

Responses

200

Successful Response

application/json

get

HTTPcURLJavaScriptPython

GET /api-keys HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

200

Successful Response

[
  {
    "owner": "text",
    "rate_limit": "text",
    "is_active": true,
    "key": "text"
  }
]

Create Api Key

post

Create a new API key (admin only)

Authorizations

Body

ownerstringRequired

rate_limitstringOptionalDefault: 100/hour

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /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"
}

Get Current Api Key

get

Get details of the current API key

Authorizations

Responses

200

Successful Response

application/json

get

HTTPcURLJavaScriptPython

GET /api-keys/me HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

200

Successful Response

{
  "owner": "text",
  "rate_limit": "text",
  "is_active": true,
  "key": "text"
}

Deactivate Api Key

delete

Deactivate an API key (admin only)

Authorizations

Path parameters

keystringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

delete

HTTPcURLJavaScriptPython

DELETE /api-keys/{key} HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Utility Endpoints

Search Pdb

get

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.

Authorizations

Query parameters

querystringRequired

Search query for PDB IDs

pageinteger · min: 1Optional

Page number to return (1-based)

Default: 1

page_sizeinteger · min: 1 · max: 1000Optional

Number of results per page

Default: 100

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /search?query=text HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "matches": [
    {
      "pdb_id": "text",
      "source": "text"
    }
  ],
  "total": 1
}

Get Pdb Info

get

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.

Authorizations

Path parameters

pdb_idstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

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"
}

Get Pdb File

get

Retrieve the PDB file for a given PDB ID. First checks the S3 bucket, if not found falls back to RCSB or PDBe sources.

Path parameters

pdb_idstringRequired

Query parameters

input_sourceanyRequired

The source of the PDB file to download

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /pdb/{pdb_id}/file?input_source=null HTTP/1.1
Host: 
Accept: */*

No content

Get Pdb Images

get

Retrieve PDB structure image URLs from S3 bucket. Returns URLs for both small (200px) and large (800px) versions of the image.

Authorizations

Path parameters

pdb_idstringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /pdb/{pdb_id}/images HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Get Job Pool Status

get

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.

Authorizations

Query parameters

statusstring · enumRequiredPossible values:

job_idsany ofOptional

List of specific job IDs to filter by

string[]Optional

or

nullOptional

pdb_searchany ofOptional

Search query for PDB IDs

stringOptional

or

nullOptional

pageinteger · min: 1Optional

Page number to return (1-based)

Default: 1

page_sizeinteger · min: 1 · max: 1000Optional

Number of results per page

Default: 100

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /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
}

Get Job

get

Retrieve a specific job by its ID.

Authorizations

Path parameters

job_idstringRequired

Query parameters

mock_minersbooleanOptional

Whether to return mock miner data instead of real data

Default: false

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /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": ""
}