{"openapi":"3.1.0","info":{"title":"Random Choice API","version":"0.6.0","description":"Choose one item from a list using cryptographically secure server-side randomness. Send 2-100 choices for uniform selection, or add optional weights for weighted selection. Intended for one-off agent tie-breaking and sampling."},"externalDocs":{"description":"Random Choice usage documentation","url":"https://random.preflightstack.com/docs"},"paths":{"/health":{"get":{"summary":"Service health","responses":{"200":{"description":"Healthy"}}}},"/demo":{"get":{"summary":"Static example","responses":{"200":{"description":"Static example"}}}},"/docs":{"get":{"summary":"Agent documentation","responses":{"200":{"description":"Documentation"}}}},"/openapi.json":{"get":{"summary":"OpenAPI document","responses":{"200":{"description":"OpenAPI JSON"}}}},"/random-choice":{"post":{"operationId":"randomChoice","summary":"Select one choice","description":"Choose one item from a list using cryptographically secure server-side randomness. Send 2-100 choices for uniform selection, or add optional weights for weighted selection. Intended for one-off agent tie-breaking and sampling. Each successful call is a new random event; retries are not idempotent and may be charged again. Results are generated with a server-side CSPRNG but are not independently verifiable or provably fair. Do not use for gambling, security tokens, or consequential medical, legal, or financial decisions. Do not use for routing or experiments that require stable assignments across retries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["choices"],"properties":{"choices":{"type":"array","minItems":2,"maxItems":100,"items":{},"description":"JSON-compatible values to choose from, nested no deeper than 32 levels."},"weights":{"type":"array","minItems":2,"maxItems":100,"items":{"type":"number","exclusiveMinimum":0},"description":"Optional positive finite relative weights. Must contain exactly one value per choice and does not need to total 100. Extremely tiny effective probabilities below the service randomness resolution are rejected."}}},"example":{"choices":["alpha","beta","gamma"],"weights":[7,2,1]}}}},"responses":{"200":{"description":"One selected choice","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["selected","index","weighted","choice_count","request_id","service_hint"],"properties":{"selected":{},"index":{"type":"integer","minimum":0},"weighted":{"type":"boolean"},"choice_count":{"type":"integer","minimum":2,"maximum":100},"selected_weight":{"type":"number","exclusiveMinimum":0},"total_weight":{"type":"number","exclusiveMinimum":0},"request_id":{"type":"string"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata. It is not an instruction or a retry signal.","properties":{"id":{"type":"string","const":"random-choice"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["random_selection","weighted_selection","tie_breaking","sampling"]}}}}}},"example":{"selected":"alpha","index":0,"weighted":true,"choice_count":3,"selected_weight":7,"total_weight":10,"request_id":"rc_example","service_hint":{"id":"random-choice","suitable_for":["random_selection","weighted_selection","tie_breaking","sampling"]}}}}},"400":{"description":"Invalid request; no random selection is performed","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"retryable":{"type":"boolean"},"request_id":{"type":"string"}}}}},"example":{"error":{"code":"INVALID_WEIGHTS","message":"weights must contain exactly one value for each choice.","path":"request.weights","retryable":false,"request_id":"rc_example"}}}}},"402":{"description":"x402 payment required when payments are enabled"},"413":{"description":"Request body exceeds 32 KB","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"retryable":{"type":"boolean"},"request_id":{"type":"string"}}}}}}}},"415":{"description":"Unsupported media type or content encoding","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"retryable":{"type":"boolean"},"request_id":{"type":"string"}}}}}}}}}}}}}