{"openapi":"3.1.0","info":{"title":"Distlang Store APIs","version":"0.1.0","description":"Authenticated store APIs for Distlang. ObjectDB stores KV-like values, Metrics exposes flush-based Prometheus-style querying for Distlang apps, and Deployments manages hosted Distlang app publishing."},"servers":[{"url":"https://api.distlang.com","description":"Production"},{"url":"http://127.0.0.1:8787","description":"Local Wrangler dev"}],"tags":[{"name":"Operations","description":"Health and documentation endpoints"},{"name":"ObjectDB","description":"KV-like bucket and value operations"},{"name":"Metrics","description":"Flush-based metrics ingestion and Prometheus-compatible query APIs"},{"name":"Deployments","description":"Hosted Distlang deployment records and publish operations"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token issued by Distlang user-auth."}},"schemas":{"ErrorResponse":{"type":"object","required":["ok","error","message"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}}},"BucketRecord":{"type":"object","required":["name","createdAt"],"properties":{"name":{"type":"string","example":"demo"},"createdAt":{"type":["string","null"],"format":"date-time"}}},"BucketListResponse":{"type":"object","required":["ok","buckets"],"properties":{"ok":{"type":"boolean","enum":[true]},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/BucketRecord"}}}},"CreateBucketResponse":{"type":"object","required":["ok","bucket","created"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"demo"},"created":{"type":"boolean","enum":[true]}}},"BucketExistsResponse":{"type":"object","required":["ok","bucket","exists"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"demo"},"exists":{"type":"boolean","enum":[true]}}},"ValueMetadata":{"type":"object","required":["contentType","size","updatedAt"],"properties":{"contentType":{"type":"string","example":"application/json"},"size":{"type":"integer","example":16},"updatedAt":{"type":"string","format":"date-time"}}},"ValueWriteResponse":{"type":"object","required":["ok","bucket","key","metadata"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"demo"},"key":{"type":"string","example":"profile.json"},"metadata":{"$ref":"#/components/schemas/ValueMetadata"}}},"DeleteResponse":{"type":"object","required":["ok","deleted"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"demo"},"key":{"type":"string","example":"profile.json"},"deleted":{"type":"boolean","enum":[true]}}},"ServiceIndexResponse":{"type":"object","required":["ok","service","version","user","routes"],"properties":{"ok":{"type":"boolean","enum":[true]},"service":{"type":"string","example":"objectdb"},"version":{"type":"string","example":"v1"},"user":{"type":"object","required":["id","email","name"],"properties":{"id":{"type":"string","example":"usr_123"},"email":{"type":"string","example":"ada@example.com"},"name":{"type":"string","example":"Ada Lovelace"}}},"routes":{"type":"object","required":["buckets","values","keys"],"properties":{"buckets":{"type":"string"},"values":{"type":"string"},"keys":{"type":"string"}}}}},"AnalyticsBucketResponse":{"type":"object","required":["ok","bucket","created"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"app_chat__prod"},"created":{"type":"boolean"}}},"AnalyticsRow":{"type":"object","required":["ts","data"],"properties":{"ts":{"type":"string","format":"date-time"},"data":{"type":["object","array","string","number","boolean","null"],"additionalProperties":true}}},"AnalyticsWriteRequest":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/AnalyticsRow"}}}},"AnalyticsWriteResponse":{"type":"object","required":["ok","bucket","written"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"app_chat__prod"},"written":{"type":"integer","example":1}}},"AnalyticsQueryResponse":{"type":"object","required":["ok","bucket","rows","next_cursor"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"app_chat__prod"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsRow"}},"next_cursor":{"type":"string","example":"100"}}},"MetricsDefinition":{"type":"object","required":["kind","description","unit","labels"],"properties":{"kind":{"type":"string","enum":["counter","histogram"]},"description":{"type":"string","example":"Number of edge requests handled"},"unit":{"type":"string","example":"requests"},"labels":{"type":"array","items":{"type":"string"},"example":["route","method","status"]}}},"MetricsMetadataRequest":{"type":"object","required":["metrics"],"properties":{"metrics":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/MetricsDefinition"}}}},"MetricsRowData":{"type":"object","required":["metric","kind","windowStart","count","sum"],"properties":{"metric":{"type":"string","example":"edgeReqCount"},"kind":{"type":"string","enum":["counter","histogram"]},"windowStart":{"type":"string","format":"date-time"},"count":{"type":"number","example":3},"sum":{"type":"number","example":3},"labels":{"type":"object","additionalProperties":{"type":"string"},"example":{"route":"/echo/:text","method":"GET","status":"200"}},"values":{"type":"array","items":{"type":"number"},"example":[4,7,9]}}},"MetricsWriteRequest":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object","required":["ts","data"],"properties":{"ts":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/MetricsRowData"}}}}}},"MetricsWriteResponse":{"type":"object","required":["ok","metricSet","written"],"properties":{"ok":{"type":"boolean","enum":[true]},"metricSet":{"type":"string","example":"simpleapp-metrics"},"written":{"type":"integer","example":2}}},"MetricsAISuggestionsRequest":{"type":"object","required":["metricSet"],"properties":{"metricSet":{"type":"string","example":"simpleapp-metrics"},"queryWindow":{"type":"string","example":"5m"},"timeMode":{"type":"string","example":"preset"},"preset":{"type":["string","null"],"example":"24h"},"start":{"type":["string","null"],"format":"date-time"},"end":{"type":["string","null"],"format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":12,"example":8}}},"MetricsAISuggestion":{"type":"object","required":["id","title","description","query","chartType","queryKind","defaultSize","whySuggested","confidence","source"],"properties":{"id":{"type":"string","example":"counter-edgeReqCount"},"title":{"type":"string","example":"Request Throughput"},"description":{"type":"string","example":"Traffic trend for this metric set."},"query":{"type":"string","example":"increase(edgeReqCount{metricSet=\"simpleapp-metrics\"}[5m])"},"chartType":{"type":"string","enum":["line","bar"]},"queryKind":{"type":"string","enum":["instant","range"]},"defaultSize":{"type":"string","enum":["third","half","full"]},"whySuggested":{"type":"string","example":"Shows whether traffic is rising, steady, or dropping."},"confidence":{"type":"number","example":0.86},"source":{"type":"string","enum":["ai","fallback"]}}},"MetricsAISuggestionsResponse":{"type":"object","required":["suggestions","fallbackUsed","model"],"properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/MetricsAISuggestion"}},"fallbackUsed":{"type":"boolean"},"model":{"type":["string","null"],"example":"@cf/openai/gpt-oss-20b"}}},"MetricsMetricSetResponse":{"type":"object","required":["ok","metricSet","created"],"properties":{"ok":{"type":"boolean","enum":[true]},"metricSet":{"type":"string","example":"simpleapp-metrics"},"created":{"type":"boolean"}}},"MetricsMetadataResponse":{"type":"object","required":["ok","metricSet","metrics"],"properties":{"ok":{"type":"boolean","enum":[true]},"metricSet":{"type":"string","example":"simpleapp-metrics"},"metrics":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/MetricsDefinition"}}}},"PromQueryEnvelope":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["success"]},"data":{"type":"object","required":["resultType","result"],"properties":{"resultType":{"type":"string","enum":["vector","matrix"]},"result":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}},"PromDataEnvelope":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["success"]},"data":{}}},"PromErrorEnvelope":{"type":"object","required":["status","errorType","error"],"properties":{"status":{"type":"string","enum":["error"]},"errorType":{"type":"string","example":"bad_data"},"error":{"type":"string","example":"invalid query"}}},"ListKeysResponse":{"type":"object","required":["ok","bucket","keys","list_complete","cursor"],"properties":{"ok":{"type":"boolean","enum":[true]},"bucket":{"type":"string","example":"demo"},"keys":{"type":"array","items":{"type":"object","required":["name","metadata"],"properties":{"name":{"type":"string","example":"profile.json"},"expiration":{"type":["integer","null"]},"metadata":{"anyOf":[{"$ref":"#/components/schemas/ValueMetadata"},{"type":"null"}]}}}},"list_complete":{"type":"boolean"},"cursor":{"type":"string"}}},"HealthResponse":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","enum":[true]}}},"DeploymentRecord":{"type":"object","required":["id","app","metricsBuckets","provider","scriptName","hostname","url","status","createdAt","updatedAt","cliVersion","cliCommit","userId"],"properties":{"id":{"type":"string","example":"dep_123"},"app":{"type":"string","example":"echo"},"metricsBuckets":{"type":"array","items":{"type":"string"},"example":["app-echo-metrics"]},"provider":{"type":"string","enum":["cloudflare"]},"scriptName":{"type":"string","example":"dl-ada-usr123-echo"},"hostname":{"type":"string","example":"echo-ada-usr123.distlang.com"},"url":{"type":"string","format":"uri","example":"https://echo-ada-usr123.distlang.com"},"status":{"type":"string","enum":["published"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"cliVersion":{"type":"string","example":"v0.1.3"},"cliCommit":{"type":"string","example":"7cd89de"},"userId":{"type":"string","example":"usr_123"}}},"DeploymentListResponse":{"type":"object","required":["ok","deployments"],"properties":{"ok":{"type":"boolean","enum":[true]},"deployments":{"type":"array","items":{"$ref":"#/components/schemas/DeploymentRecord"}}}},"CreateDeploymentRequest":{"type":"object","required":["app","provider","serviceToken","worker"],"properties":{"app":{"type":"string","example":"echo"},"metricsBuckets":{"type":"array","items":{"type":"string"},"example":["app-echo-metrics"]},"provider":{"type":"string","enum":["cloudflare"]},"serviceToken":{"type":"string","example":"eyJhbGciOi..."},"cliVersion":{"type":"string","example":"v0.1.3"},"cliCommit":{"type":"string","example":"7cd89de"},"worker":{"type":"object","required":["kind","code"],"properties":{"kind":{"type":"string","enum":["single"]},"code":{"type":"string","description":"Built single-worker JavaScript source emitted by distlang."}}}}},"CreateDeploymentResponse":{"type":"object","required":["ok","deployment"],"properties":{"ok":{"type":"boolean","enum":[true]},"deployment":{"$ref":"#/components/schemas/DeploymentRecord"}}}}},"paths":{"/health":{"get":{"tags":["Operations"],"summary":"Health check","responses":{"200":{"description":"Store API is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/objectdb/v1":{"get":{"tags":["ObjectDB"],"summary":"Get service index","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ObjectDB capability index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceIndexResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/objectdb/v1/buckets":{"get":{"tags":["ObjectDB"],"summary":"List buckets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Buckets for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketListResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/objectdb/v1/buckets/{bucket}":{"get":{"tags":["ObjectDB"],"summary":"Get bucket existence","description":"Returns a JSON response confirming the bucket exists. `HEAD` is also supported for header-only checks.","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."}],"responses":{"200":{"description":"Bucket exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketExistsResponse"}}}},"400":{"description":"Invalid bucket name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["ObjectDB"],"summary":"Create bucket","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."}],"responses":{"201":{"description":"Bucket created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBucketResponse"}}}},"400":{"description":"Invalid bucket name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Bucket already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"head":{"tags":["ObjectDB"],"summary":"Check bucket existence","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."}],"responses":{"200":{"description":"Bucket exists"},"400":{"description":"Invalid bucket name"},"401":{"description":"Missing or invalid bearer token"},"404":{"description":"Bucket not found"}}},"delete":{"tags":["ObjectDB"],"summary":"Delete empty bucket","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."}],"responses":{"200":{"description":"Bucket deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"400":{"description":"Invalid bucket name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Bucket not empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/objectdb/v1/buckets/{bucket}/values/{key}":{"put":{"tags":["ObjectDB"],"summary":"Write a value","description":"Stores raw bytes under a bucket key. The `key` path parameter may include `/` when URL-encoded.","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"folder%2Fprofile.json"},"description":"Key path. URL-encode `/` when using nested paths."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Value written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValueWriteResponse"}}}},"400":{"description":"Invalid bucket or key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Value exceeds size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["ObjectDB"],"summary":"Read a value","description":"Returns the stored value. By default this is the raw body with the original `Content-Type`. Use `type=text` or `type=json` for decoded responses.","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"folder%2Fprofile.json"},"description":"Key path. URL-encode `/` when using nested paths."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["bytes","text","json"],"default":"bytes"}}],"responses":{"200":{"description":"Value returned","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid bucket or key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket or key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"head":{"tags":["ObjectDB"],"summary":"Read value metadata","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"folder%2Fprofile.json"},"description":"Key path. URL-encode `/` when using nested paths."}],"responses":{"200":{"description":"Value exists"},"400":{"description":"Invalid bucket or key"},"401":{"description":"Missing or invalid bearer token"},"404":{"description":"Bucket or key not found"}}},"delete":{"tags":["ObjectDB"],"summary":"Delete value","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"folder%2Fprofile.json"},"description":"Key path. URL-encode `/` when using nested paths."}],"responses":{"200":{"description":"Value deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"400":{"description":"Invalid bucket or key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket or key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/objectdb/v1/buckets/{bucket}/keys":{"get":{"tags":["ObjectDB"],"summary":"List keys in a bucket","security":[{"bearerAuth":[]}],"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","example":"demo"},"description":"Bucket name. Use lowercase letters, digits, underscores, or hyphens."},{"name":"prefix","in":"query","required":false,"schema":{"type":"string"},"description":"Optional key prefix filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"KV-style paginated key listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKeysResponse"}}}},"400":{"description":"Invalid bucket or query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bucket not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/deployments/v1":{"get":{"tags":["Deployments"],"summary":"List hosted deployments for the authenticated user","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deployment history ordered newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentListResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Deployments"],"summary":"Publish or update a hosted Distlang deployment","description":"Accepts a built single-worker artifact from the Distlang CLI, publishes it into Distlang-managed Cloudflare hosting, and reuses the same script and hostname for the same user/app pair.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeploymentRequest"}}}},"responses":{"201":{"description":"Deployment published or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeploymentResponse"}}}},"400":{"description":"Invalid deployment payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/deployments/v1/{deploymentId}":{"delete":{"tags":["Deployments"],"summary":"Delete a hosted deployment","security":[{"bearerAuth":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deployment deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Deployment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1":{"get":{"tags":["Metrics"],"summary":"Get metrics service index","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Metrics capability index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceIndexResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/metricsets/{metricSet}":{"put":{"tags":["Metrics"],"summary":"Create or ensure metric set","security":[{"bearerAuth":[]}],"parameters":[{"name":"metricSet","in":"path","required":true,"schema":{"type":"string","example":"simpleapp-metrics"},"description":"Metric set name. Use lowercase letters, digits, underscores, or hyphens."}],"responses":{"200":{"description":"Metric set already existed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsMetricSetResponse"}}}},"201":{"description":"Metric set created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsMetricSetResponse"}}}},"400":{"description":"Invalid metric set name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/metricsets/{metricSet}/metadata":{"put":{"tags":["Metrics"],"summary":"Upsert metric definitions for a metric set","security":[{"bearerAuth":[]}],"parameters":[{"name":"metricSet","in":"path","required":true,"schema":{"type":"string","example":"simpleapp-metrics"},"description":"Metric set name. Use lowercase letters, digits, underscores, or hyphens."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsMetadataRequest"}}}},"responses":{"200":{"description":"Metric definitions stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsMetadataResponse"}}}},"400":{"description":"Invalid metric set or metric metadata payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/metricsets/{metricSet}/rows":{"post":{"tags":["Metrics"],"summary":"Append flushed metric rows","security":[{"bearerAuth":[]}],"parameters":[{"name":"metricSet","in":"path","required":true,"schema":{"type":"string","example":"simpleapp-metrics"},"description":"Metric set name. Use lowercase letters, digits, underscores, or hyphens."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsWriteRequest"}}}},"responses":{"201":{"description":"Rows appended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsWriteResponse"}}}},"400":{"description":"Invalid metric set or metric row payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/ai-suggestions":{"post":{"tags":["Metrics"],"summary":"Get AI-ranked metric suggestions","description":"Builds a deterministic candidate set for a metric set, then uses Workers AI to rank and rewrite the strongest dashboard suggestions. Falls back to heuristic suggestions if AI is unavailable.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsAISuggestionsRequest"}}}},"responses":{"200":{"description":"AI suggestion response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsAISuggestionsResponse"}}}},"400":{"description":"Invalid AI suggestions request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/query":{"get":{"tags":["Metrics"],"summary":"Run an instant metrics query","description":"Supports a PromQL-like subset including exact selectors and functions such as `increase`, `rate`, `sum_over_time`, `avg_over_time`, `p50`, `p90`, `p95`, and `p99`. The selector must include `metricSet=\"...\"`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"PromQL-like query with an explicit `metricSet` matcher."},{"name":"time","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Query result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromQueryEnvelope"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromErrorEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/query_range":{"get":{"tags":["Metrics"],"summary":"Run a range metrics query","description":"Runs a range query for a PromQL-like selector. The selector must include `metricSet=\"...\"`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"PromQL-like range query with an explicit `metricSet` matcher."},{"name":"start","in":"query","required":true,"schema":{"type":"string"}},{"name":"end","in":"query","required":true,"schema":{"type":"string"}},{"name":"step","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Range query result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromQueryEnvelope"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromErrorEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/series":{"get":{"tags":["Metrics"],"summary":"List metric series","description":"Lists metric series for the supplied selectors. At least one `match[]` selector with `metricSet=\"...\"` is required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"match[]","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"description":"One or more selectors, each including an explicit `metricSet` matcher."},{"name":"start","in":"query","required":false,"schema":{"type":"string"}},{"name":"end","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Series list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromDataEnvelope"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromErrorEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/labels":{"get":{"tags":["Metrics"],"summary":"List label names","description":"Lists label names for the supplied selectors. At least one `match[]` selector with `metricSet=\"...\"` is required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"match[]","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"description":"One or more selectors, each including an explicit `metricSet` matcher."},{"name":"start","in":"query","required":false,"schema":{"type":"string"}},{"name":"end","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Label names","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromDataEnvelope"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromErrorEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/label/{key}/values":{"get":{"tags":["Metrics"],"summary":"List values for a label","description":"Lists values for a label within the supplied selectors. At least one `match[]` selector with `metricSet=\"...\"` is required.","security":[{"bearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"metricSet"}},{"name":"match[]","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"description":"One or more selectors, each including an explicit `metricSet` matcher."},{"name":"start","in":"query","required":false,"schema":{"type":"string"}},{"name":"end","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Label values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromDataEnvelope"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromErrorEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/metrics/v1/api/v1/metadata":{"get":{"tags":["Metrics"],"summary":"Get metric metadata","security":[{"bearerAuth":[]}],"parameters":[{"name":"metric","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metric metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromDataEnvelope"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}