{"components":{"responses":{},"schemas":{},"securitySchemes":{"bearer":{"bearerFormat":"API_SECRET","description":"API key secret (format: unsb-sk-xxxxx-xxxxx-xxxxx-xxxxx)","scheme":"bearer","type":"http"}}},"info":{"description":"API endpoints for managing API key validation, rate limiting, and execution tracking.\n\nThese endpoints are called by api.unsandbox.com to:\n- Validate API keys and retrieve configuration\n- Track request consumption for rate limiting\n- Check throttle status for upstream decisions\n- Track concurrent executions\n\n**Authentication**: All endpoints require a valid API key secret in the `Authorization` header.\n","title":"Unsandbox API Key Management API","version":"1.0.0"},"openapi":"3.0.0","paths":{"/keys/am-i-throttled":{"post":{"callbacks":{},"description":"Fast throttle check for upstream decisions. Only returns last 60s requests and active executions. Optimized for speed - no expensive usage calculations.","operationId":"UnsandboxWeb.APIKeyController.throttle","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"active_executions":{"description":"Currently running executions (allocated containers)","type":"integer"},"burst":{"description":"Maximum requests per minute","type":"integer"},"concurrency":{"description":"Maximum concurrent executions","type":"integer"},"requests_used_in_last_60s":{"description":"Requests in current minute window","type":"integer"},"should_throttle":{"description":"Overall throttle recommendation","type":"boolean"},"should_throttle_concurrency":{"description":"Throttle due to concurrency limit","type":"boolean"},"should_throttle_rate":{"description":"Throttle due to rate limit","type":"boolean"}},"type":"object"}}},"description":"Throttle status"}},"security":[{"bearer":[]}],"summary":"Check if API key should be throttled","tags":["API Keys"]}},"/keys/end":{"post":{"callbacks":{},"description":"End an execution (decrement active_executions). Called by api.unsandbox.com when an execution finishes or times out.","operationId":"UnsandboxWeb.APIKeyController.end_execution","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"active_executions":{"description":"Current active executions after decrement","type":"integer"},"concurrency_limit":{"type":"integer"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Execution ended"}},"security":[{"bearer":[]}],"summary":"End an execution","tags":["API Keys"]}},"/keys/start":{"post":{"callbacks":{},"description":"Start an execution (consumes a request, increments active_executions, updates usage stats). Called by api.unsandbox.com when an execution begins.","operationId":"UnsandboxWeb.APIKeyController.start_execution","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"active_executions":{"description":"Current active executions","type":"integer"},"concurrency_limit":{"type":"integer"},"remaining":{"description":"Remaining requests in current minute","type":"integer"},"reset_at":{"description":"Unix timestamp when rate limit resets","format":"int64","type":"integer"},"success":{"example":true,"type":"boolean"}},"type":"object"}}},"description":"Execution started"},"429":{"content":{"application/json":{"schema":{"oneOf":[{"properties":{"burst":{"type":"integer"},"error":{"example":"rate_limit_exceeded","type":"string"},"rate_per_minute":{"type":"integer"},"reset_at":{"format":"int64","type":"integer"},"success":{"example":false,"type":"boolean"}},"type":"object"},{"properties":{"active_executions":{"type":"integer"},"concurrency_limit":{"type":"integer"},"error":{"example":"concurrency_limit_reached","type":"string"},"retry_after_ms":{"example":5000,"type":"integer"},"success":{"example":false,"type":"boolean"}},"type":"object"}],"type":"object"}}},"description":"Rate limit or concurrency limit exceeded"}},"security":[{"bearer":[]}],"summary":"Start an execution","tags":["API Keys"]}},"/keys/stats":{"post":{"callbacks":{},"description":"Returns detailed usage statistics across all time windows. Use this for analytics dashboards, not for throttling decisions.","operationId":"UnsandboxWeb.APIKeyController.stats","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"active_executions":{"description":"Currently running executions","type":"integer"},"burst":{"description":"Maximum requests per minute","type":"integer"},"concurrency":{"description":"Maximum concurrent executions","type":"integer"},"requests_used_in_last_60s":{"description":"Requests in current minute window","type":"integer"},"usage":{"description":"Usage statistics across time windows (ordered from smallest to largest)","items":{"properties":{"count":{"description":"Number of requests in this window","example":4,"type":"integer"},"window":{"description":"Time window label","example":"last_60s","type":"string"}},"required":["window","count"],"type":"object"},"type":"array"}},"type":"object"}}},"description":"Usage statistics"}},"security":[{"bearer":[]}],"summary":"Get API key usage statistics","tags":["API Keys"]}},"/keys/validate":{"post":{"callbacks":{},"description":"Validate an API key and return its configuration. Responses are cacheable for hours to reduce load.","operationId":"UnsandboxWeb.APIKeyController.validate","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"burst":{"example":120,"type":"integer"},"cached_until":{"format":"int64","type":"integer"},"concurrency":{"example":5,"type":"integer"},"rate_per_minute":{"example":60,"type":"integer"},"status":{"example":"active","type":"string"},"tier":{"example":"starter","type":"string"},"valid":{"example":true,"type":"boolean"},"valid_for_human":{"description":"Human-readable time remaining","example":"29 days","type":"string"},"valid_through":{"description":"Unix timestamp (milliseconds) when key expires","format":"int64","type":"integer"},"valid_through_datetime":{"description":"ISO 8601 datetime when key expires","example":"2025-12-21T10:30:45Z","format":"date-time","type":"string"}},"type":"object"}}},"description":"Valid API key"},"401":{"content":{"application/json":{"schema":{"properties":{"cached_until":{"format":"int64","type":"integer"},"reason":{"enum":["invalid_key","expired","suspended"],"type":"string"},"valid":{"example":false,"type":"boolean"}},"type":"object"}}},"description":"Invalid API key"}},"security":[{"bearer":[]}],"summary":"Validate API key","tags":["API Keys"]}}},"security":[],"servers":[{"url":"https://unsandbox.com","variables":{}}],"tags":[]}