For agents and applications

A private question.
A mysterious answer.

Draw one curated blackball prompt for an end user without transmitting their question. The experience is playful reflection—not analysis, advice, or prediction.

GET /api/v1/prompts/random

The contract

Ask for an answer, not the question.

Never send the end user’s question to blackball. Let them hold it privately, then request a prompt with an empty GET request.

curl --request GET \
  --header 'Accept: application/json' \
  https://blackball.app/api/v1/prompts/random

{
  "schema_version": "1.0",
  "answer": {
    "id": "v1.wait-missing-piece",
    "text": "Wait for the missing piece.",
    "category": "wait",
    "tone": "uncertain"
  },
  "framing": {
    "kind": "playful_reflection",
    "not_advice": true,
    "not_a_prediction": true,
    "high_stakes_use": false
  },
  "privacy": {
    "question_received": false,
    "question_stored": false
  },
  "source_url": "https://blackball.app/"
}

Website draw behavior

Recorded when connected, local when unavailable.

The blackball website normally sends an empty POST /api/v1/draws. The backend selects the prompt and stores only an internal event UUID, answer ID, and server-generated timestamp before returning it. It never receives the private question, user-entered text, an account ID, or a browser session ID.

If that request fails, times out, is rate-limited, or returns an invalid response, the website falls back to local selection from the same catalog. Local fallback draws are not recorded or uploaded later.

Recommended interaction

Keep the ritual intact.

01 — Invite privacy

Tell the person to hold their question in mind rather than entering or sharing it.

02 — Draw once

Call the endpoint without parameters or a request body.

03 — Quote faithfully

Present the returned text as “The blackball says…” without claiming it analyzed the decision.

04 — Notice the reaction

Optionally ask whether the prompt brought relief, resistance, recognition, or uncertainty.

Boundaries

Mysterious, but not misleading.

Safety

Every result is for entertainment and reflection. It is not advice or a prediction. Do not use it as the basis for medical, legal, financial, mental-health, crisis, safety-critical, or other high-stakes decisions.

Privacy

The Agent API has no question field, request body, account, cookie, or personalization. Website backend-issued draws record only an internal event UUID, answer ID, and server-generated timestamp; fallback draws remain local. Hosting infrastructure may process ordinary network request metadata to deliver and protect the service.

Availability

A best-effort anonymous rate limit allows 60 requests per one-hour runtime window. The application uses a temporary, one-way network-address identifier in runtime memory; it is not a durable identity or cross-session profile.

HTTP behavior

Successful responses are JSON with Cache-Control: no-store. CORS permits public read access without credentials. Handle 405, 429, and transient server errors gracefully.

A private question.A mysterious answer.