8Ball API Documentation
Complete reference guide to integrate fortune telling into your applications
Introduction
The 8Ball API provides a simple and fun way to get mystical responses to yes/no questions. With this API, you can easily integrate a fortune-telling feature into your Discord bots, games, and other applications.
This API is RESTful and returns JSON, making it easy to integrate with any programming language or framework.
Getting Started
The Magic 8 Ball API is free to use and doesn't require an API key for basic usage. Simply make a request to the API endpoint with your question, and you'll receive a response in JSON format.
Base URL
https://eightballapi.comAPI Endpoints
Get Random Fortune
Returns a random Magic 8 Ball response.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locale | string | No | The language code for response localization (e.g., en, es, fr, de, hi, ru) |
Response Format
{
"reading": "Outlook good",
"locale": "en" // Only included for non-default locale
}Get Categories
Returns all responses grouped by category (positive, negative, neutral).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locale | string | No | The language code for response localization (e.g., en, es, fr, de, hi, ru) |
Response Format
{
"positive": [
"It is Certain.",
"It is decidedly so.",
// ... more positive responses
],
"neutral": [
"Reply hazy, try again.",
"Ask again later.",
// ... more neutral responses
],
"negative": [
"Don't count on it.",
"My reply is no.",
// ... more negative responses
],
"locale": "en"
}Get Specific Category
Returns a random response from a specific category (positive, negative, or neutral).
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | Yes | The category of response (positive, negative, or neutral) |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locale | string | No | The language code for response localization (e.g., en, es, fr, de, hi, ru) |
Response Format
{
"reading": "It is Certain.",
"category": "positive",
"locale": "en"
}Get Biased Fortune
Returns a biased Magic 8 Ball response based on the sentiment of your question.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| question | string | Yes | The question to analyze for sentiment |
| lucky | boolean | No | Whether to give a "lucky" response (default: false) |
| locale | string | No | The language code for response localization (e.g., en, es, fr, de, hi, ru) |
Response Format
{
"reading": "My reply is no.",
"question": "Will I win the lottery?",
"sentiment": {
"score": 4,
"comparative": 0.8,
"calculation": [{"win": 4}],
"tokens": ["Will", "I", "win", "the", "lottery?"],
"words": ["Win"],
"positive": ["Win"],
"negative": []
},
"locale": "en",
"lucky": false
}Alternative method to get a biased response by sending parameters in the request body.
Request Body
{
"question": "Will I succeed?", // Required
"lucky": true, // Optional, defaults to false
"locale": "fr" // Optional, defaults to "en"
}Response Format
{
"reading": "Ma réponse est non.",
"question": "Will I succeed?",
"sentiment": {
"score": 2,
"comparative": 0.6667,
"calculation": [{"succeed": 2}],
"tokens": ["Will", "I", "succeed?"],
"words": ["succeed"],
"positive": ["succeed"],
"negative": []
},
"locale": "fr",
"lucky": true
}Localization
The 8Ball API supports multiple languages. You can request localized responses by adding the locale parameter to your requests.
| Locale Code | Language |
|---|---|
| en | English (default) |
| es | Spanish |
| fr | French |
| de | German |
| hi | Hindi |
| ru | Russian |
Example: GET /api/positive?locale=fr
Returns a random positive response in French.
Usage Limits
The Magic 8 Ball API is free to use with reasonable usage limits:
- Rate limit: 100 requests per minute per IP address
- No authentication required for standard usage