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

X-API-KeystringRequired

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

Represents a response from a validator.

uidsinteger[]Required

The uids of the response.

hotkeysstring[]Required

The hotkeys of the response.

422

Validation Error

application/json

post

/fold

POST /fold HTTP/1.1
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

X-API-KeystringRequired

Body

pdb_filestring · binaryRequired

querystringRequired

Responses

200

Successful Response

application/json

Represents a response from a validator.

uidsinteger[]Required

The uids of the response.

hotkeysstring[]Required

The hotkeys of the response.

422

Validation Error

application/json

post

/fold/upload

POST /fold/upload HTTP/1.1
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"
  ]
}

List Api Keys

get

List all API keys (admin only)

Authorizations

X-API-KeystringRequired

Responses

200

Successful Response

application/json

ownerstringRequired

rate_limitstringRequired

is_activebooleanOptionalDefault: true

keystringRequired

get

/api-keys

GET /api-keys HTTP/1.1
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

X-API-KeystringRequired

Body

ownerstringRequired

rate_limitstringOptionalDefault: 100/hour

Responses

200

Successful Response

application/json

ownerstringRequired

rate_limitstringRequired

is_activebooleanOptionalDefault: true

keystringRequired

422

Validation Error

application/json

post

/api-keys

POST /api-keys HTTP/1.1
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

X-API-KeystringRequired

Responses

200

Successful Response

application/json

ownerstringRequired

rate_limitstringRequired

is_activebooleanOptionalDefault: true

keystringRequired

get

/api-keys/me

GET /api-keys/me HTTP/1.1
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

X-API-KeystringRequired

Path parameters

keystringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

delete

/api-keys/{key}

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

No content

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

X-API-KeystringRequired

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

Represents a response from a PDB search.

totalintegerRequired

Total number of matches found

422

Validation Error

application/json

get

/search

GET /search?query=text HTTP/1.1
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

X-API-KeystringRequired

Path parameters

pdb_idstringRequired

Responses

200

Successful Response

application/json

Represents detailed information about a PDB structure from RCSB.

pdb_idstringRequired

PDB ID

molecule_nameany ofOptional

Name of the molecule/protein

stringOptional

or

nullOptional

classificationany ofOptional

Structural classification

stringOptional

or

nullOptional

organismany ofOptional

Source organism

stringOptional

or

nullOptional

expression_systemany ofOptional

Expression system used

stringOptional

or

nullOptional

422

Validation Error

application/json

get

/pdb/{pdb_id}

GET /pdb/{pdb_id} HTTP/1.1
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

anyOptional

422

Validation Error

application/json

get

/pdb/{pdb_id}/file

GET /pdb/{pdb_id}/file?input_source=null HTTP/1.1
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

X-API-KeystringRequired

Path parameters

pdb_idstringRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

get

/pdb/{pdb_id}/images

GET /pdb/{pdb_id}/images HTTP/1.1
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

X-API-KeystringRequired

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

Represents a response from a job pool.

totalintegerRequired

Total number of jobs

422

Validation Error

application/json

get

/job_pool

GET /job_pool?status=active HTTP/1.1
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

X-API-KeystringRequired

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

pdb_idstringRequired

pdb_datastringRequired

pdb_file_linkstringRequired

organismany ofOptional

Source organism

stringOptional

or

nullOptional

classificationany ofOptional

Structural classification

stringOptional

or

nullOptional

expression_systemany ofOptional

Expression system used

stringOptional

or

nullOptional

mutationsany ofOptional

Mutations in the PDB

booleanOptional

or

nullOptional

sourcestringRequired

temperaturenumberRequired

frictionnumberRequired

pressurenumberRequired

time_to_livenumberRequired

ffstringRequired

waterstringRequired

boxstringRequired

statusstring · enumOptional

Job status

Default: inactivePossible values:

created_atstringOptional

Job creation timestamp

Default: ""

updated_atstringOptional

Job last update timestamp

Default: ""

422

Validation Error

application/json

get

/job_pool/{job_id}

GET /job_pool/{job_id} HTTP/1.1
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": ""
}

Core Folding Endpoints

Fold

Fold With Upload

API Key Management

List Api Keys

Create Api Key

Get Current Api Key

Deactivate Api Key

Utility Endpoints

Search Pdb

Get Pdb Info

Get Pdb File

Get Pdb Images

Get Job Pool Status

Get Job

hashtagCore Folding Endpoints

hashtagFold

hashtagFold With Upload

hashtagAPI Key Management

hashtagList Api Keys

hashtagCreate Api Key

hashtagGet Current Api Key

hashtagDeactivate Api Key

hashtagUtility Endpoints

hashtagSearch Pdb

hashtagGet Pdb Info

hashtagGet Pdb File

hashtagGet Pdb Images

hashtagGet Job Pool Status

hashtagGet Job

Core Folding Endpoints

Fold

Fold With Upload

API Key Management

List Api Keys

Create Api Key

Get Current Api Key

Deactivate Api Key

Utility Endpoints

Search Pdb

Get Pdb Info

Get Pdb File

Get Pdb Images

Get Job Pool Status

Get Job