{"openapi":"3.1.0","info":{"title":"SRI Monitoring API","description":"HTTP JSON API for monitoring SV2 applications","contact":{"name":"The Stratum V2 Developers"},"license":{"name":"MIT OR Apache-2.0","identifier":"MIT OR Apache-2.0"},"version":"0.1.0"},"paths":{"/api/v1/clients":{"get":{"tags":["clients"],"summary":"Get all Sv2 clients (downstream) - returns metadata only, use /clients/{id}/channels for\nchannels","operationId":"handle_clients","parameters":[{"name":"offset","in":"query","description":"Offset for pagination (default: 0)","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Limit for pagination (default: 25, max: 100)","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"List of Sv2 clients (metadata only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sv2ClientsResponse"}}}},"404":{"description":"Sv2 clients monitoring not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/{client_id}":{"get":{"tags":["clients"],"summary":"Get a single Sv2 client by ID - returns metadata only, use /clients/{id}/channels for channels","operationId":"handle_client_by_id","parameters":[{"name":"client_id","in":"path","description":"Sv2 Client ID","required":true,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Sv2 client metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sv2ClientResponse"}}}},"404":{"description":"Sv2 client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clients/{client_id}/channels":{"get":{"tags":["clients"],"summary":"Get channels for a specific Sv2 client (paginated)","operationId":"handle_client_channels","parameters":[{"name":"client_id","in":"path","description":"Sv2 Client ID","required":true,"schema":{"type":"integer","minimum":0}},{"name":"offset","in":"query","description":"Offset for pagination (default: 0)","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Limit for pagination (default: 25, max: 100)","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"Sv2 client channels (paginated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sv2ClientChannelsResponse"}}}},"404":{"description":"Sv2 client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/global":{"get":{"tags":["global"],"summary":"Get global statistics","description":"Returns aggregated statistics for the server (upstream) and clients (downstream).\nFields are omitted from the response if that type of monitoring is not enabled.\n\n**Typical responses:**\n- **Pool/JDC**: `server` + `clients` (Sv2 downstream)\n- **tProxy**: `server` + `sv1_clients` (Sv1 miners)","operationId":"handle_global","responses":{"200":{"description":"Global statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalInfo"}}}}}}},"/api/v1/health":{"get":{"tags":["health"],"summary":"Health check endpoint","operationId":"handle_health","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/server":{"get":{"tags":["server"],"summary":"Get server (upstream) metadata - use /server/channels for channel details","operationId":"handle_server","responses":{"200":{"description":"Server metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerResponse"}}}},"404":{"description":"Server monitoring not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/server/channels":{"get":{"tags":["server"],"summary":"Get server channels (paginated)","operationId":"handle_server_channels","parameters":[{"name":"offset","in":"query","description":"Offset for pagination (default: 0)","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Limit for pagination (default: 25, max: 100)","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"Server channels (paginated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerChannelsResponse"}}}},"404":{"description":"Server monitoring not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/sv1/clients":{"get":{"tags":["sv1"],"summary":"Get Sv1 clients (Translator Proxy only)","operationId":"handle_sv1_clients","parameters":[{"name":"offset","in":"query","description":"Offset for pagination (default: 0)","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Limit for pagination (default: 25, max: 100)","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"List of Sv1 clients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sv1ClientsResponse"}}}},"404":{"description":"Sv1 monitoring not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/sv1/clients/{client_id}":{"get":{"tags":["sv1"],"summary":"Get a single Sv1 client by ID","operationId":"handle_sv1_client_by_id","parameters":[{"name":"client_id","in":"path","description":"Sv1 client ID","required":true,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Sv1 client details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sv1ClientInfo"}}}},"404":{"description":"Sv1 client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ExtendedChannelInfo":{"type":"object","description":"Information about an extended channel","required":["channel_id","user_identity","nominal_hashrate","target_hex","requested_max_target_hex","extranonce_prefix_hex","full_extranonce_size","rollable_extranonce_size","expected_shares_per_minute","shares_accepted","share_work_sum","last_share_sequence_number","best_diff","last_batch_accepted","last_batch_work_sum","share_batch_size","blocks_found"],"properties":{"best_diff":{"type":"number","format":"double"},"blocks_found":{"type":"integer","format":"int32","minimum":0},"channel_id":{"type":"integer","format":"int32","minimum":0},"expected_shares_per_minute":{"type":"number","format":"float"},"extranonce_prefix_hex":{"type":"string"},"full_extranonce_size":{"type":"integer","minimum":0},"last_batch_accepted":{"type":"integer","format":"int32","minimum":0},"last_batch_work_sum":{"type":"number","format":"double"},"last_share_sequence_number":{"type":"integer","format":"int32","minimum":0},"nominal_hashrate":{"type":"number","format":"float"},"requested_max_target_hex":{"type":"string"},"rollable_extranonce_size":{"type":"integer","format":"int32","minimum":0},"share_batch_size":{"type":"integer","minimum":0},"share_work_sum":{"type":"number","format":"double"},"shares_accepted":{"type":"integer","format":"int32","minimum":0},"target_hex":{"type":"string"},"user_identity":{"type":"string"}}},"GlobalInfo":{"type":"object","description":"Global statistics from `/api/v1/global` endpoint\n\nFields are `Option` to distinguish \"not monitored\" (`None`) from \"monitored but empty\" (`Some`\nwith zeros).\n\nTypical configurations:\n- **Pool/JDC**: `server` and `sv2_clients` are `Some`, `sv1_clients` is `None`\n- **tProxy**: `server` and `sv1_clients` are `Some`, `sv2_clients` is `None`","required":["uptime_secs"],"properties":{"server":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ServerSummary","description":"Server (upstream) summary - `None` if server monitoring is not enabled"}]},"sv1_clients":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Sv1ClientsSummary","description":"Sv1 clients summary - `None` if Sv1 monitoring is not enabled (e.g., Pool/JDC)"}]},"sv2_clients":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Sv2ClientsSummary","description":"Sv2 clients (downstream) summary - `None` if Sv2 client monitoring is not enabled (e.g.,\ntProxy)"}]},"uptime_secs":{"type":"integer","format":"int64","description":"Uptime in seconds since the application started","minimum":0}}},"HealthResponse":{"type":"object","required":["status","timestamp"],"properties":{"status":{"type":"string"},"timestamp":{"type":"integer","format":"int64","minimum":0}}},"ServerChannelsResponse":{"type":"object","required":["offset","limit","total_extended","total_standard","extended_channels","standard_channels"],"properties":{"extended_channels":{"type":"array","items":{"$ref":"#/components/schemas/ServerExtendedChannelInfo"}},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"standard_channels":{"type":"array","items":{"$ref":"#/components/schemas/ServerStandardChannelInfo"}},"total_extended":{"type":"integer","minimum":0},"total_standard":{"type":"integer","minimum":0}}},"ServerExtendedChannelInfo":{"type":"object","description":"Information about an extended channel opened with the server","required":["channel_id","user_identity","target_hex","extranonce_prefix_hex","full_extranonce_size","rollable_extranonce_size","version_rolling","shares_acknowledged","shares_submitted","shares_rejected","shares_rejected_by_reason","share_work_sum","best_diff","blocks_found"],"properties":{"best_diff":{"type":"number","format":"double"},"blocks_found":{"type":"integer","format":"int32","minimum":0},"channel_id":{"type":"integer","format":"int32","minimum":0},"extranonce_prefix_hex":{"type":"string"},"full_extranonce_size":{"type":"integer","minimum":0},"nominal_hashrate":{"type":["number","null"],"format":"float","description":"None when vardiff is disabled and hashrate cannot be reliably tracked"},"rollable_extranonce_size":{"type":"integer","format":"int32","minimum":0},"share_work_sum":{"type":"number","format":"double"},"shares_acknowledged":{"type":"integer","format":"int32","minimum":0},"shares_rejected":{"type":"integer","format":"int32","minimum":0},"shares_rejected_by_reason":{"type":"object","additionalProperties":{"type":"integer","format":"int32","minimum":0},"propertyNames":{"type":"string"}},"shares_submitted":{"type":"integer","format":"int32","minimum":0},"target_hex":{"type":"string"},"user_identity":{"type":"string"},"version_rolling":{"type":"boolean"}}},"ServerResponse":{"type":"object","required":["extended_channels_count","standard_channels_count","total_hashrate"],"properties":{"extended_channels_count":{"type":"integer","minimum":0},"standard_channels_count":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}},"ServerStandardChannelInfo":{"type":"object","description":"Information about a standard channel opened with the server","required":["channel_id","user_identity","target_hex","extranonce_prefix_hex","shares_acknowledged","shares_submitted","shares_rejected","shares_rejected_by_reason","share_work_sum","best_diff","blocks_found"],"properties":{"best_diff":{"type":"number","format":"double"},"blocks_found":{"type":"integer","format":"int32","minimum":0},"channel_id":{"type":"integer","format":"int32","minimum":0},"extranonce_prefix_hex":{"type":"string"},"nominal_hashrate":{"type":["number","null"],"format":"float","description":"None when vardiff is disabled and hashrate cannot be reliably tracked"},"share_work_sum":{"type":"number","format":"double"},"shares_acknowledged":{"type":"integer","format":"int32","minimum":0},"shares_rejected":{"type":"integer","format":"int32","minimum":0},"shares_rejected_by_reason":{"type":"object","additionalProperties":{"type":"integer","format":"int32","minimum":0},"propertyNames":{"type":"string"}},"shares_submitted":{"type":"integer","format":"int32","minimum":0},"target_hex":{"type":"string"},"user_identity":{"type":"string"}}},"ServerSummary":{"type":"object","description":"Aggregate information about the server connection","required":["total_channels","extended_channels","standard_channels","total_hashrate"],"properties":{"extended_channels":{"type":"integer","minimum":0},"standard_channels":{"type":"integer","minimum":0},"total_channels":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}},"StandardChannelInfo":{"type":"object","description":"Information about a standard channel","required":["channel_id","user_identity","nominal_hashrate","target_hex","requested_max_target_hex","extranonce_prefix_hex","expected_shares_per_minute","shares_accepted","share_work_sum","last_share_sequence_number","best_diff","last_batch_accepted","last_batch_work_sum","share_batch_size","blocks_found"],"properties":{"best_diff":{"type":"number","format":"double"},"blocks_found":{"type":"integer","format":"int32","minimum":0},"channel_id":{"type":"integer","format":"int32","minimum":0},"expected_shares_per_minute":{"type":"number","format":"float"},"extranonce_prefix_hex":{"type":"string"},"last_batch_accepted":{"type":"integer","format":"int32","minimum":0},"last_batch_work_sum":{"type":"number","format":"double"},"last_share_sequence_number":{"type":"integer","format":"int32","minimum":0},"nominal_hashrate":{"type":"number","format":"float"},"requested_max_target_hex":{"type":"string"},"share_batch_size":{"type":"integer","minimum":0},"share_work_sum":{"type":"number","format":"double"},"shares_accepted":{"type":"integer","format":"int32","minimum":0},"target_hex":{"type":"string"},"user_identity":{"type":"string"}}},"Sv1ClientInfo":{"type":"object","description":"Information about a single SV1 client connection","required":["client_id","authorized_worker_name","user_identity","target_hex","extranonce1_hex","extranonce2_len"],"properties":{"authorized_worker_name":{"type":"string"},"channel_id":{"type":["integer","null"],"format":"int32","minimum":0},"client_id":{"type":"integer","minimum":0},"extranonce1_hex":{"type":"string"},"extranonce2_len":{"type":"integer","minimum":0},"hashrate":{"type":["number","null"],"format":"float"},"target_hex":{"type":"string"},"user_identity":{"type":"string"},"version_rolling_mask":{"type":["string","null"]},"version_rolling_min_bit":{"type":["string","null"]}}},"Sv1ClientsResponse":{"type":"object","required":["offset","limit","total","items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Sv1ClientInfo"}},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"Sv1ClientsSummary":{"type":"object","description":"Aggregate information about SV1 client connections","required":["total_clients","total_hashrate"],"properties":{"total_clients":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}},"Sv2ClientChannelsResponse":{"type":"object","required":["client_id","offset","limit","total_extended","total_standard","extended_channels","standard_channels"],"properties":{"client_id":{"type":"integer","minimum":0},"extended_channels":{"type":"array","items":{"$ref":"#/components/schemas/ExtendedChannelInfo"}},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"standard_channels":{"type":"array","items":{"$ref":"#/components/schemas/StandardChannelInfo"}},"total_extended":{"type":"integer","minimum":0},"total_standard":{"type":"integer","minimum":0}}},"Sv2ClientInfo":{"type":"object","description":"Full information about a single Sv2 client including all channels","required":["client_id","extended_channels","standard_channels"],"properties":{"client_id":{"type":"integer","minimum":0},"extended_channels":{"type":"array","items":{"$ref":"#/components/schemas/ExtendedChannelInfo"}},"standard_channels":{"type":"array","items":{"$ref":"#/components/schemas/StandardChannelInfo"}}}},"Sv2ClientMetadata":{"type":"object","description":"Sv2 client metadata without channel arrays (for listings)","required":["client_id","extended_channels_count","standard_channels_count","total_hashrate"],"properties":{"client_id":{"type":"integer","minimum":0},"extended_channels_count":{"type":"integer","minimum":0},"standard_channels_count":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}},"Sv2ClientResponse":{"type":"object","required":["client_id","extended_channels_count","standard_channels_count","total_hashrate"],"properties":{"client_id":{"type":"integer","minimum":0},"extended_channels_count":{"type":"integer","minimum":0},"standard_channels_count":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}},"Sv2ClientsResponse":{"type":"object","required":["offset","limit","total","items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Sv2ClientMetadata"}},"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"Sv2ClientsSummary":{"type":"object","description":"Aggregate information about all Sv2 clients","required":["total_clients","total_channels","extended_channels","standard_channels","total_hashrate"],"properties":{"extended_channels":{"type":"integer","minimum":0},"standard_channels":{"type":"integer","minimum":0},"total_channels":{"type":"integer","minimum":0},"total_clients":{"type":"integer","minimum":0},"total_hashrate":{"type":"number","format":"float"}}}}},"tags":[{"name":"health","description":"Health check endpoints"},{"name":"global","description":"Global statistics"},{"name":"server","description":"Server (upstream) monitoring"},{"name":"clients","description":"Clients (downstream) monitoring"},{"name":"sv1","description":"Sv1 clients monitoring (Translator Proxy only)"}]}