{"openapi":"3.1.0","info":{"title":"Letsur Platform API","description":"고객이 Platform Management Key(`mk_...`)로 자기 스페이스의 사용량·유닛 잔액을 조회하는 공개 API. 모델 호출용 Gateway Key(`sk_...`)로는 호출할 수 없습니다.","version":"v0.0.2-dev3"},"servers":[{"url":"https://openapi.letsur.ai/v1"}],"security":[{"ManagementKey":[]}],"paths":{"/usage":{"get":{"summary":"Get Usage","description":"Return the caller's space monthly usage (Management Key auth).","operationId":"get_usage_usage_get","tags":["usage"],"security":[{"ManagementKey":[]}],"parameters":[{"name":"month","in":"query","required":false,"description":"Target month (KST) as YYYY-MM. Defaults to the current month.","schema":{"title":"Month","description":"Target month (KST) as YYYY-MM. Defaults to the current month.","anyOf":[{"type":"string","pattern":"^\\d{4}-(?:0[1-9]|1[0-2])$"},{"type":"null"}]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/balance":{"get":{"summary":"Get Balance","description":"Return the caller's space unit balance (Management Key auth).","operationId":"get_balance_balance_get","tags":["balance"],"security":[{"ManagementKey":[]}],"parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"UsageResponse":{"type":"object","title":"UsageResponse","description":"External monthly usage response for the Management-Key usage API.","required":["periodStart","periodEnd","totalCostUsage","totalRequestCount","activeVirtualKeyCount","costsByModel","costsByVirtualKey"],"properties":{"periodStart":{"type":"string","title":"Periodstart","format":"date-time"},"periodEnd":{"type":"string","title":"Periodend","format":"date-time"},"totalCostUsage":{"type":"string","title":"Totalcostusage","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"totalRequestCount":{"type":"integer","title":"Totalrequestcount"},"activeVirtualKeyCount":{"type":"integer","title":"Activevirtualkeycount"},"costsByModel":{"type":"array","title":"Costsbymodel","items":{"$ref":"#/components/schemas/UsageModelCostResponse"}},"costsByVirtualKey":{"type":"array","title":"Costsbyvirtualkey","items":{"$ref":"#/components/schemas/UsageVirtualKeyCostResponse"}}}},"HTTPValidationError":{"type":"object","title":"HTTPValidationError","properties":{"detail":{"type":"array","title":"Detail","items":{"$ref":"#/components/schemas/ValidationError"}}}},"BalanceResponse":{"type":"object","title":"BalanceResponse","description":"External unit balance response for the Management-Key balance API.","required":["held","overage","blocked"],"properties":{"held":{"$ref":"#/components/schemas/BalanceHeldResponse"},"overage":{"$ref":"#/components/schemas/BalanceOverageResponse"},"blocked":{"type":"boolean","title":"Blocked"}}},"UsageModelCostResponse":{"type":"object","title":"UsageModelCostResponse","description":"Model-level usage cost.","required":["model","cost","requestCount"],"properties":{"model":{"type":"string","title":"Model"},"cost":{"type":"string","title":"Cost","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"requestCount":{"type":"integer","title":"Requestcount"}}},"UsageVirtualKeyCostResponse":{"type":"object","title":"UsageVirtualKeyCostResponse","description":"Virtual-key-level usage cost (name-based).","required":["virtualKeyName","cost","requestCount"],"properties":{"virtualKeyName":{"type":"string","title":"Virtualkeyname"},"creatorNickname":{"title":"Creatornickname","anyOf":[{"type":"string"},{"type":"null"}]},"cost":{"type":"string","title":"Cost","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"requestCount":{"type":"integer","title":"Requestcount"}}},"ValidationError":{"type":"object","title":"ValidationError","required":["loc","msg","type"],"properties":{"loc":{"type":"array","title":"Location","items":{"anyOf":[{"type":"string"},{"type":"integer"}]}},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}}},"BalanceHeldResponse":{"type":"object","title":"BalanceHeldResponse","description":"Held (available) unit credit, split by source.","required":["promo","paid","total"],"properties":{"promo":{"type":"string","title":"Promo","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"paid":{"type":"string","title":"Paid","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"total":{"type":"string","title":"Total","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}}},"BalanceOverageResponse":{"type":"object","title":"BalanceOverageResponse","description":"Overage (over-limit) unit usage and whether it is allowed.","required":["accrued","allowed"],"properties":{"accrued":{"type":"string","title":"Accrued","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},"allowed":{"type":"boolean","title":"Allowed"}}}},"securitySchemes":{"ManagementKey":{"type":"http","scheme":"bearer","description":"Platform Management Key (mk_...)"}}}}