REST API for creating and managing Ethereum Distributed Validator clusters — cluster definitions, locks, validator states, exits, deposits, fee recipients, effectiveness, peer scores, Techne credentials, and network staking metrics (OpenAPI 3.0.0).
{"openapi":"3.0.0","paths":{"/":{"get":{"description":"Hitting the root of the domain redirects to /docs and a swagger deployment.","operationId":"AppController_redirect","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"summary":"Redirect to the API docs","tags":["System"]}},"/v1/_health":{"get":{"description":"This endpoint reports the API and its dependencies health.","operationId":"HealthController_check_v1","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Check the API health","tags":["System"]}},"/metrics":{"get":{"operationId":"MetricsController_metrics","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"string"}}}}},"tags":["Metrics"]}},"/v1/definition/{configHash}":{"get":{"description":"This endpoint allows a charon client or launchpad interface to retrieve the terms of a proposed DKG. Once all operators listed in the DKG have submitted signed approvals to the terms, this object will be ready for a cluster of operators to use as part of a DKG ceremony. If the objects in the `operators` array are not fully populated, these operators need to use the [PUT request](#/Distributed%20Validators/DefinitionController_updateClusterDefinition) to upload their charon client's public key and a signature from their address to indicate their acceptance of the terms.","operationId":"DefinitionController_getClusterDefinition_v1","parameters":[{"name":"configHash","required":true,"in":"path","description":"The `config_hash` calculated for a cluster definition.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterDefinitionResponse"}]}}}},"404":{"description":"Cluster definition not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a Distributed Validator Cluster proposal","tags":["Cluster Definition"]},"put":{"description":"This endpoint is used by the operators present in the `operators` array of a cluster definition. The operator must have accepted the latest version of [Obol's terms and conditions](https://obol.tech/terms.pdf). These operators must submit a public key (in ENR form) to serve as their identity during the DKG, along with EIP712 signatures indicating their acceptance of the terms of this DKG.","operationId":"DefinitionController_updateClusterDefinition_v1","parameters":[{"name":"authorization","required":true,"in":"header","description":"EIP712 operator hash as bearer token","schema":{"type":"string"}},{"name":"configHash","required":true,"in":"path","description":"The `config_hash` calculated for a cluster definition.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperatorDto"}}}},"responses":{"200":{"description":"The cluster object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterDefinitionResponse"}]}}}},"400":{"description":"Invalid payload data"},"401":{"description":"Missing t&c signature\n\nAuthorization header is missing or incorrect"},"404":{"description":"Data not found"},"409":{"description":"Duplicate entry"},"500":{"description":"An unknown error occurred"}},"security":[{"bearer":[]}],"summary":"Accept a proposed Distributed Validator Cluster","tags":["Cluster Definition"]}},"/v1/definition/operator":{"get":{"description":"This endpoint allows a charon client or launchpad interface to fetch a specific number of cluster definitions which the address is part of for each page.","operationId":"DefinitionController_getClusterDefinitionWithOperator[0]_v1","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"limit","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"A list of cluster definitions which the operator is part of","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterDefinitionPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of cluster definitions which the address belongs to.","tags":["Cluster Definition"]}},"/v1/definition/operator/{address}":{"get":{"description":"This endpoint allows a charon client or launchpad interface to fetch a specific number of cluster definitions which the address is part of for each page.","operationId":"DefinitionController_getClusterDefinitionWithOperator[1]_v1","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"limit","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"A list of cluster definitions which the operator is part of","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterDefinitionPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of cluster definitions which the address belongs to.","tags":["Cluster Definition"]}},"/v1/definition":{"post":{"description":"This endpoint allows the caller to propose a distributed key generation ceremony.The caller must have accepted the latest version of [Obol's terms and conditions](https://obol.tech/terms.pdf). The caller must specify the configuration of a Distributed Validator Cluster; such as the participating operators and the validator exit details. Operators invited to participate in this cluster must submit a public key (in [ENR](https://docs.obol.tech/docs/v0.12.0/int/faq/errors#enrs-keys) form) to serve as their node's identity, along with EIP712 signatures indicating their acceptance of the terms of this cluster.","operationId":"DefinitionController_postClusterDefinition_v1","parameters":[{"name":"authorization","required":true,"in":"header","description":"EIP712 cluster definition hash as bearer token","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterDefDto"}}}},"responses":{"201":{"description":"The cluster object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterDefinitionResponse"}]}}}},"400":{"description":"Invalid definition data"},"401":{"description":"Missing t&c signature\n\nAuthorization header is missing or incorrect"},"409":{"description":"Duplicate entry"},"500":{"description":"An unknown error occurred"}},"security":[{"bearer":[]}],"summary":"Propose a new Distributed Validator Cluster","tags":["Cluster Definition"]}},"/lock/{lockHash}":{"get":{"description":"This endpoint is used to retrieve a cluster lock object.","operationId":"LockController_getClusterLock[0]","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster lock object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a Distributed Validator Cluster Lock Object","tags":["Cluster Lock"]}},"/v1/lock/{lockHash}":{"get":{"description":"This endpoint is used to retrieve a cluster lock object.","operationId":"LockController_getClusterLock[1]_v1","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster lock object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a Distributed Validator Cluster Lock Object","tags":["Cluster Lock"]}},"/lock/search/{network}":{"get":{"description":"This endpoint is used to search for Cluster Lock Objects that match a substring of their `lock_hash`.","operationId":"LockController_searchClusterLocks[0]","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"},"sepolia":{"summary":"Sepolia Test Network","value":"sepolia"}},"schema":{"type":"string"}},{"name":"partialLockHash","required":true,"in":"query","description":"A substring of the `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}},{"name":"partialClusterName","required":true,"in":"query","description":"A substring of the cluster name.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the lock hash matches.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Cluster Lock Objects","tags":["Cluster Lock"]}},"/v1/lock/search/{network}":{"get":{"description":"This endpoint is used to search for Cluster Lock Objects that match a substring of their `lock_hash`.","operationId":"LockController_searchClusterLocks[1]_v1","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"},"sepolia":{"summary":"Sepolia Test Network","value":"sepolia"}},"schema":{"type":"string"}},{"name":"partialLockHash","required":true,"in":"query","description":"A substring of the `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}},{"name":"partialClusterName","required":true,"in":"query","description":"A substring of the cluster name.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the lock hash matches.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Cluster Lock Objects","tags":["Cluster Lock"]}},"/lock/configHash/{configHash}":{"get":{"description":"This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it.","operationId":"LockController_getLockByConfigHash[0]","parameters":[{"name":"configHash","required":true,"in":"path","description":"The `config_hash` calculated for a cluster configuration.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster lock object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a Distributed Validator Cluster Lock Object","tags":["Cluster Lock"]}},"/v1/lock/configHash/{configHash}":{"get":{"description":"This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it.","operationId":"LockController_getLockByConfigHash[1]_v1","parameters":[{"name":"configHash","required":true,"in":"path","description":"The `config_hash` calculated for a cluster configuration.","schema":{"type":"string"}}],"responses":{"200":{"description":"The cluster lock object","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"404":{"description":"Cluster not found"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a Distributed Validator Cluster Lock Object","tags":["Cluster Lock"]}},"/lock/{lockHash}/launchpad":{"get":{"description":"This endpoint is used to redirect users to the created cluster status page after DKG is completed.","operationId":"LockController_redirectToClusterStatus[0]","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a Distributed Validator Cluster.","schema":{"type":"string"}}],"responses":{"302":{"description":"Serves a redirect to the launchpad cluster status page"},"404":{"description":"Cluster lock not found"},"500":{"description":"An unknown error occurred"}},"summary":"Redirect to the launchpad cluster status page","tags":["Cluster Lock"]}},"/v1/lock/{lockHash}/launchpad":{"get":{"description":"This endpoint is used to redirect users to the created cluster status page after DKG is completed.","operationId":"LockController_redirectToClusterStatus[1]_v1","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a Distributed Validator Cluster.","schema":{"type":"string"}}],"responses":{"302":{"description":"Serves a redirect to the launchpad cluster status page"},"404":{"description":"Cluster lock not found"},"500":{"description":"An unknown error occurred"}},"summary":"Redirect to the launchpad cluster status page","tags":["Cluster Lock"]}},"/lock/{lockHash}/peer-scores":{"get":{"description":"This endpoint returns the average peer_score for each operator address in a cluster lock within a specified date range. Results are sorted by peer_score in descending order.","operationId":"LockController_getAveragePeerScores[0]","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date for the range (ISO 8601 format). If not provided, defaults to endDate - 7 days.","schema":{"example":"2026-01-21T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for the range (ISO 8601 format). If not provided, defaults to the latest available date.","schema":{"example":"2026-01-28T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"Array of operator addresses with their average peer scores","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"operator_address":{"type":"string","example":"0x7a82E643B0c8AE619f71d9667559180c33c92277"},"avg_peer_score":{"type":"number","example":99.89},"peer_name":{"type":"string","example":"puzzled-pen","nullable":true,"description":"Peer name shown when the peer score row has no operator address."},"peer_nickname":{"type":"string","example":"Alice node","nullable":true,"description":"Operator-configured peer nickname, when available."},"last_updated":{"type":"string","format":"date-time","example":"2026-02-10T00:00:00.000Z","description":"Latest peer_score date included in this averaged rank row."}}}}}}},"400":{"description":"Network error - unable to determine network from fork_version\n\nInvalid date format"},"404":{"description":"Cluster lock not found"},"500":{"description":"An unknown error occurred"}},"summary":"Get average peer scores for operators in a cluster","tags":["Cluster Lock"]}},"/v1/lock/{lockHash}/peer-scores":{"get":{"description":"This endpoint returns the average peer_score for each operator address in a cluster lock within a specified date range. Results are sorted by peer_score in descending order.","operationId":"LockController_getAveragePeerScores[1]_v1","parameters":[{"name":"lockHash","required":true,"in":"path","description":"The `lock_hash` calculated for a cluster lock.","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date for the range (ISO 8601 format). If not provided, defaults to endDate - 7 days.","schema":{"example":"2026-01-21T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for the range (ISO 8601 format). If not provided, defaults to the latest available date.","schema":{"example":"2026-01-28T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"Array of operator addresses with their average peer scores","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"operator_address":{"type":"string","example":"0x7a82E643B0c8AE619f71d9667559180c33c92277"},"avg_peer_score":{"type":"number","example":99.89},"peer_name":{"type":"string","example":"puzzled-pen","nullable":true,"description":"Peer name shown when the peer score row has no operator address."},"peer_nickname":{"type":"string","example":"Alice node","nullable":true,"description":"Operator-configured peer nickname, when available."},"last_updated":{"type":"string","format":"date-time","example":"2026-02-10T00:00:00.000Z","description":"Latest peer_score date included in this averaged rank row."}}}}}}},"400":{"description":"Network error - unable to determine network from fork_version\n\nInvalid date format"},"404":{"description":"Cluster lock not found"},"500":{"description":"An unknown error occurred"}},"summary":"Get average peer scores for operators in a cluster","tags":["Cluster Lock"]}},"/lock/operator":{"get":{"description":"This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.","operationId":"LockController_getClusterLocksByOperator[0]","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the operator is a member of.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for which this address is an operator","tags":["Cluster Lock"]}},"/lock/operator/{address}":{"get":{"description":"This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.","operationId":"LockController_getClusterLocksByOperator[1]","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the operator is a member of.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for which this address is an operator","tags":["Cluster Lock"]}},"/v1/lock/operator":{"get":{"description":"This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.","operationId":"LockController_getClusterLocksByOperator[2]_v1","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the operator is a member of.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for which this address is an operator","tags":["Cluster Lock"]}},"/v1/lock/operator/{address}":{"get":{"description":"This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.","operationId":"LockController_getClusterLocksByOperator[3]_v1","parameters":[{"name":"address","required":true,"in":"path","description":"The operator address.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"A list of Distributed Validator Clusters which the operator is a member of.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for which this address is an operator","tags":["Cluster Lock"]}},"/lock/network/{network}":{"get":{"description":"This endpoint fetches a number of cluster lock objects for a given network.","operationId":"LockController_getClusterLocksByNetwork[0]","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"},"sepolia":{"summary":"Sepolia Test Network","value":"sepolia"}},"schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}},{"name":"sortBy","required":false,"in":"query","description":"numerical field to sort by","schema":{"type":"string","default":"avg_effectiveness"}},{"name":"sortOrder","required":false,"in":"query","description":"order of sorting the field","schema":{"type":"string","default":"desc"}},{"name":"pool","required":false,"in":"query","description":"cluster type or pool","schema":{"type":"string"}},{"name":"details","required":true,"in":"query","description":"The flag to populate cluster definition information.","schema":{"type":"string","default":"false"}}],"responses":{"200":{"description":"A paged list of Distributed Validator Clusters on this network","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"400":{"description":"Network not spported"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for a given network","tags":["Cluster Lock"]}},"/v1/lock/network/{network}":{"get":{"description":"This endpoint fetches a number of cluster lock objects for a given network.","operationId":"LockController_getClusterLocksByNetwork[1]_v1","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"},"sepolia":{"summary":"Sepolia Test Network","value":"sepolia"}},"schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page number to retrieve.","schema":{"type":"integer","default":0}},{"name":"limit","required":true,"in":"query","description":"The number of cluster lock objects to return.","schema":{"type":"integer","default":100}},{"name":"sortBy","required":false,"in":"query","description":"numerical field to sort by","schema":{"type":"string","default":"avg_effectiveness"}},{"name":"sortOrder","required":false,"in":"query","description":"order of sorting the field","schema":{"type":"string","default":"desc"}},{"name":"pool","required":false,"in":"query","description":"cluster type or pool","schema":{"type":"string"}},{"name":"details","required":true,"in":"query","description":"The flag to populate cluster definition information.","schema":{"type":"string","default":"false"}}],"responses":{"200":{"description":"A paged list of Distributed Validator Clusters on this network","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockPagedResponse"}]}}}},"400":{"description":"Network not spported"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for a given network","tags":["Cluster Lock"]}},"/lock/network/summary/{network}":{"get":{"description":"This endpoint fetches a nsummary of the lock files stored for a given network","operationId":"LockController_getClusterLockNetworkSummary[0]","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"}},"schema":{"type":"string"}}],"responses":{"200":{"description":"A summary of the Distributed Validator locks for a given network","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockNetworkSummaryResponse"}]}}}},"400":{"description":"Network not spported"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for a given network","tags":["Cluster Lock"]}},"/v1/lock/network/summary/{network}":{"get":{"description":"This endpoint fetches a nsummary of the lock files stored for a given network","operationId":"LockController_getClusterLockNetworkSummary[1]_v1","parameters":[{"name":"network","required":true,"in":"path","description":"The network to retrieve clusters on","examples":{"mainnet":{"summary":"Ethereum Mainnet","value":"mainnet"},"hoodi":{"summary":"Hoodi Test Network","value":"hoodi"}},"schema":{"type":"string"}}],"responses":{"200":{"description":"A summary of the Distributed Validator locks for a given network","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockNetworkSummaryResponse"}]}}}},"400":{"description":"Network not spported"},"500":{"description":"An unknown error occurred"}},"summary":"Retrieve a list of Distributed Validator Clusters for a given network","tags":["Cluster Lock"]}},"/lock":{"post":{"description":"This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster. If the lock_hash is already stored, the existing lock is returned (idempotent; no re-validation) with the same 201 response.","operationId":"LockController_postClusterLock[0]","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterLockDto"}}}},"responses":{"201":{"description":"The cluster lock object (new publish or idempotent retry for an existing lock_hash).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"400":{"description":"Invalid lock data"},"404":{"description":"The cluster definition corresponding to this lock file was not found"},"500":{"description":"An unknown error occurred"},"503":{"description":"Too many lock validations in progress on this instance. Retry with backoff."},"504":{"description":"Lock validation exceeded the time limit (typically very large locks)."}},"summary":"Push Distributed Validator Cluster Lock Data","tags":["Cluster Lock"]}},"/v1/lock":{"post":{"description":"This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster. If the lock_hash is already stored, the existing lock is returned (idempotent; no re-validation) with the same 201 response.","operationId":"LockController_postClusterLock[1]_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterLockDto"}}}},"responses":{"201":{"description":"The cluster lock object (new publish or idempotent retry for an existing lock_hash).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusterLockResponse"}]}}}},"400":{"description":"Invalid lock data"},"404":{"description":"The cluster definition corresponding to this lock file was not found"},"500":{"description":"An unknown error occurred"},"503":{"description":"Too many lock validations in progress on this instance. Retry with backoff."},"504":{"description":"Lock validation exceeded the time limit (typically very large locks)."}},"summary":"Push Distributed Validator Cluster Lock Data","tags":["Cluster Lock"]}},"/lock/verify":{"post":{"description":"This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.","operationId":"LockController_verifyClusterLock[0]","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterLockDto"}}}},"responses":{"200":{"description":"Lock data is valid"},"400":{"description":"Invalid lock data"},"500":{"description":"An unknown error occurred"},"503":{"description":"Too many lock validations in progress on this instance. Retry with backoff."},"504":{"description":"Lock validation exceeded the time limit (typically very large locks)."}},"summary":"Verify Distributed Validator Cluster Lock Data","tags":["Cluster Lock"]}},"/v1/lock/verify":{"post":{"description":"This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.","operationId":"LockController_verifyClusterLock[1]_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterLockDto"}}}},"responses":{"200":{"description":"Lock data is valid"},"400":{"description":"Invalid lock data"},"500":{"description":"An unknown error occurred"},"503":{"description":"Too many lock validations in progress on this instance. Retry with backoff."},"504":{"description":"Lock validation exceeded the time lim
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/obol/refs/heads/main/openapi/obol-openapi-original.json