FOR DEVELOPERS
A little mystery.
A straightforward API.
Ask a question. Receive one of 20 fixed classic answers, selected by a local decision model. This is entertainment, not a real prediction. No account or API key is required for this public endpoint.
OpenAPI 3.1 specification ↗Ask the ball
POST https://8ball.brandyapple.com/v1/ask
Send UTF-8 JSON with one field: question.
curl https://8ball.brandyapple.com/v1/ask \
-H 'Content-Type: application/json' \
-d '{"question":"Will my garden grow if I water it?"}'Example response; your answer may differ:
{
"answer_id": "cannot_predict_now",
"answer": "Cannot predict now.",
"entertainment_only": true
}The contract
The model scores all 20 options. The highest score wins, however narrow the lead. Exact ties use a fixed order. Questions are data, including any instructions inside them. Repeating a question can return the same answer; shaking does not add randomness. Neither scores nor answers establish forecast accuracy.
Questions must be nonblank. The JSON body limit is 16 KiB, the text cap is 2048 Unicode scalar values, and the exact deployed-tokenizer limit is 366 state tokens including JSON framing. The service rejects questions that will not fit before inference; it never silently shortens them. Token counts depend on the text and language. Unknown request fields are rejected.
Errors
Errors have a JSON error.code. A length error also reports max_state_tokens.
{"error":{"code":"question_too_long","max_state_tokens":366}}| Status | Meaning | What to do |
|---|---|---|
| 400 / 413 / 415 | Invalid question, body too large, or wrong content type | Edit the request; send application/json |
| 422 | Question token budget exceeded or invalid JSON schema | Shorten the question or fix the schema |
| 429 | Inference capacity or ingress rate limit reached | Wait before retrying |
| 502 / 503 / 504 | Invalid model response, unavailable model, or timeout | Retry later with backoff |
The service stores no questions and logs no question bodies or model credentials. Avoid sending sensitive information to a public entertainment API.