{"openapi":"3.1.0","info":{"title":"BlakeStack Developer API","version":"1.0.0","description":"Free read-only Bitcoin BLAKE2b observations and sourced editorial pool terms. No API key. GET, HEAD and OPTIONS support CORS without credentials. Cache lifetime: up to 30 seconds. Poll no more often than every 30 seconds. Shared per-process origin budget: two requests per second, burst 30. Recorded data is mutable after chain reorganizations; retain exports for citations. Null values mean unavailable, not zero."},"servers":[{"url":"https://blakestack.com/api/v1"}],"paths":{"/network":{"get":{"summary":"Latest network observation and freshness","parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Inspect freshness and coverage metadata.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkResponse"}}}},"304":{"description":"The requested representation has not changed.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method; use GET, HEAD or OPTIONS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared origin rate limit reached; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable or service busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history":{"get":{"summary":"Recorded observation means, counts and coverage","parameters":[{"name":"from","in":"query","required":false,"description":"Inclusive UTC ISO timestamp ending in Z; default to minus 24 hours.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Exclusive UTC ISO timestamp ending in Z, no later than now. Default: latest 30-second boundary. Maximum window: 31 days.","schema":{"type":"string","format":"date-time"}},{"name":"interval","in":"query","required":false,"description":"UTC-aligned averaging interval. auto targets about 480 buckets. Maximum 10,000 buckets.","schema":{"type":"string","enum":["auto","30s","5m","1h","1d"],"default":"auto"}},{"name":"format","in":"query","required":false,"description":"Response representation.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Inspect freshness and coverage metadata.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}},"text/csv":{"schema":{"type":"string","description":"Bucket means, counts, requested period, units in column names, source, generation time and methodology. Empty data returns only column headers; coverage is also returned in X-Available-Since / Until and X-Covered-Since / Until headers when known."}}}},"304":{"description":"The requested representation has not changed.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method; use GET, HEAD or OPTIONS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared origin rate limit reached; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable or service busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/blocks":{"get":{"summary":"Stored canonical blocks in descending height order","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of blocks in this page.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"before_height","in":"query","required":false,"description":"Exclusive cursor; use meta.next_before_height. Omit for the latest page.","schema":{"type":"integer","minimum":961640,"maximum":2147483647}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Inspect freshness and coverage metadata.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocksResponse"}}}},"304":{"description":"The requested representation has not changed.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method; use GET, HEAD or OPTIONS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared origin rate limit reached; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable or service busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pools":{"get":{"summary":"Editorial pool terms with sources and review dates","parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Inspect freshness and coverage metadata.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolsResponse"}}}},"304":{"description":"The requested representation has not changed.","headers":{"ETag":{"description":"Representation identifier; send If-None-Match for conditional requests.","schema":{"type":"string"}},"Cache-Control":{"description":"Remaining freshness budget, up to 30 seconds.","schema":{"type":"string"}},"X-Generated-At":{"description":"Generation timestamp in UTC.","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method; use GET, HEAD or OPTIONS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared origin rate limit reached; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable or service busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"NetworkResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"version":{"const":"1"},"generated_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"chain":{"type":"object","properties":{"name":{"type":"string"},"fork_height":{"type":"integer"},"fork_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["name","fork_height","fork_hash"]},"methodology_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["live","stale","syncing","offline","waiting"]},"sampled_at":{"type":"string","format":"date-time"},"received_at":{"type":"string","format":"date-time"},"stale_after_seconds":{"type":"integer"},"units":{"type":"object","properties":{"hashrate_hps":{"type":"string"},"average_block_interval_seconds":{"type":"string"},"mempool_vsize":{"type":"string"},"difficulty_blake2b":{"type":"string"}},"required":["hashrate_hps","average_block_interval_seconds","mempool_vsize","difficulty_blake2b"]},"hashrate_estimate_block_window_max":{"type":"integer"},"block_interval_count":{"type":"integer"},"mempool_scope":{"type":"string"}},"required":["version","generated_at","source","chain","methodology_url","status","sampled_at","received_at","stale_after_seconds","units","hashrate_estimate_block_window_max","block_interval_count","mempool_scope"]},"data":{"type":"object","properties":{"tip_height":{"type":"integer"},"tip_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tip_time":{"type":"string","format":"date-time"},"difficulty_blake2b":{"type":"number"},"hashrate_hps":{"type":["number","null"]},"average_block_interval_seconds":{"type":["number","null"]},"mempool_transactions":{"type":"integer"},"mempool_vsize":{"type":["integer","null"]}},"required":["tip_height","tip_hash","tip_time","difficulty_blake2b","hashrate_hps","average_block_interval_seconds","mempool_transactions","mempool_vsize"]}},"required":["meta","data"]},"HistoryResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"version":{"const":"1"},"generated_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"chain":{"type":"object","properties":{"name":{"type":"string"},"fork_height":{"type":"integer"},"fork_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["name","fork_height","fork_hash"]},"methodology_url":{"type":"string","format":"uri"},"requested_window":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"interval":{"type":"string"}},"required":["from","to","interval"]},"available_since":{"type":["string","null"],"format":"date-time"},"available_until":{"type":["string","null"],"format":"date-time"},"covered_since":{"type":["string","null"],"format":"date-time"},"covered_until":{"type":["string","null"],"format":"date-time"},"bucket_seconds":{"type":"integer"},"aggregation":{"type":"string"},"units":{"type":"object","properties":{"hashrate_hps_mean":{"type":"string"},"difficulty_blake2b_mean":{"type":"string"}},"required":["hashrate_hps_mean","difficulty_blake2b_mean"]}},"required":["version","generated_at","source","chain","methodology_url","requested_window","available_since","available_until","covered_since","covered_until","bucket_seconds","aggregation","units"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoryPoint"},"maxItems":10000}},"required":["meta","data"]},"HistoryPoint":{"type":"object","properties":{"bucket_start":{"type":"string","format":"date-time"},"first_sample_at":{"type":"string","format":"date-time"},"last_sample_at":{"type":"string","format":"date-time"},"sample_count":{"type":"integer"},"hashrate_sample_count":{"type":"integer"},"hashrate_hps_mean":{"type":["number","null"]},"difficulty_blake2b_mean":{"type":"number"}},"required":["bucket_start","first_sample_at","last_sample_at","sample_count","hashrate_sample_count","hashrate_hps_mean","difficulty_blake2b_mean"]},"BlocksResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"version":{"const":"1"},"generated_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"chain":{"type":"object","properties":{"name":{"type":"string"},"fork_height":{"type":"integer"},"fork_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["name","fork_height","fork_hash"]},"methodology_url":{"type":"string","format":"uri"},"available_from_height":{"type":["integer","null"]},"limit":{"type":"integer"},"next_before_height":{"type":["integer","null"]},"ordering":{"type":"string"},"canonical_only":{"const":true},"reorg_policy":{"type":"string"},"units":{"type":"object","properties":{"size_bytes":{"type":"string"},"weight":{"type":"string"},"fees_sats":{"type":"string"}},"required":["size_bytes","weight","fees_sats"]}},"required":["version","generated_at","source","chain","methodology_url","available_from_height","limit","next_before_height","ordering","canonical_only","reorg_policy","units"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Block"},"maxItems":500}},"required":["meta","data"]},"Block":{"type":"object","properties":{"height":{"type":"integer"},"hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"previous_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"time":{"type":"string","format":"date-time"},"observed_at":{"type":"string","format":"date-time"},"difficulty_blake2b":{"type":"number"},"canonical":{"const":true},"transaction_count":{"type":["integer","null"]},"size_bytes":{"type":["integer","null"]},"weight":{"type":["integer","null"]},"fees_sats":{"type":["integer","null"]}},"required":["height","hash","previous_hash","time","observed_at","difficulty_blake2b","canonical","transaction_count","size_bytes","weight","fees_sats"]},"PoolsResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"version":{"const":"1"},"generated_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"chain":{"type":"object","properties":{"name":{"type":"string"},"fork_height":{"type":"integer"},"fork_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["name","fork_height","fork_hash"]},"methodology_url":{"type":"string","format":"uri"},"storage":{"type":"string","enum":["database","editorial"]},"live_telemetry":{"const":false},"scope":{"type":"string"}},"required":["version","generated_at","source","chain","methodology_url","storage","live_telemetry","scope"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Pool"}}},"required":["meta","data"]},"Pool":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"fee_label":{"type":"string"},"payout_method":{"type":"string"},"minimum_payout":{"type":"string"},"datum":{"type":"string","enum":["yes","no","unknown"]},"setup":{"type":"string"},"notes":{"type":"string"},"review_status":{"type":"string","enum":["checked","needs-review"]},"checked_at":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["label","url"]}}},"required":["slug","name","url","description","fee_label","payout_method","minimum_payout","datum","setup","notes","review_status","checked_at","sources"]}}}}