🔮 OccultSanctum API

Integrate astrological and numerological AI oracles into your application.

Base URL:

1. Authentication
2. Query Endpoint
3. Request Parameters
4. Response Format
5. File Attachments
6. Error Codes
7. Rate Limits
8. Examples

1. Authentication

All API requests require an API key sent via the x-api-key header.

x-api-key: os_live_your_key_here

API keys are issued by the OccultSanctum admin. Each key has daily and monthly request limits. Contact the admin to request access.

⚠️ Keep your API key secret. Do not expose it in client-side code, public repositories, or URLs.

2. Query Endpoint

POST /api/v1/query

Send a prompt to an oracle and receive an AI-generated response. Each call is stateless — there is no conversation history between requests.

3. Request Parameters

Send a JSON body with Content-Type: application/json.

Parameter	Type		Description
`appname`	string	required	The slug (identifier) of the oracle to query. Your API key determines which oracles you can access.
`email`	string	required	Email address of the end-user making the request. Used for audit logging.
`prompt`	string	required	The question or instruction to send to the oracle. Max 8,000 characters. Include any relevant details (birth date, time, place, etc.) directly in the prompt.
`files`	array	optional	Up to 3 file attachments (images or PDFs). See File Attachments for format. Only accepted by oracles that support files.

4. Response Format

Success (200)

{
  "success": true,
  "response": "Based on your birth chart, the current planetary...",
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 680,
    "latency_ms": 2340
  },
  "rate_limit": {
    "daily_remaining": 997,
    "monthly_remaining": 29997
  }
}

Field	Type	Description
`success`	boolean	Always `true` on success.
`response`	string	The AI-generated response text.
`usage.input_tokens`	integer	Tokens consumed by the prompt + context.
`usage.output_tokens`	integer	Tokens in the generated response.
`usage.latency_ms`	integer	Total processing time in milliseconds.
`rate_limit.daily_remaining`	integer	Remaining requests today.
`rate_limit.monthly_remaining`	integer	Remaining requests this month.

Error

{
  "error": "Daily request limit reached.",
  "limit": 1000,
  "used": 1000
}

5. File Attachments

Some oracles accept file attachments (e.g., palm images for palmistry analysis). Files are sent as base64-encoded data in the files array.

Field	Type	Description
`mimeType`	string	One of: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `application/pdf`
`base64`	string	Base64-encoded file content. Max 5MB per file.

{
  "appname": "palm-reader",
  "email": "user@example.com",
  "prompt": "Please analyse my palm",
  "files": [
    {
      "mimeType": "image/jpeg",
      "base64": "/9j/4AAQSkZJRgABAQAAAQ..."
    }
  ]
}

ℹ️ Maximum 3 files per request. If the oracle does not accept files, the request will be rejected with a 400 error.

6. Error Codes

Code	Meaning	Common Cause
`400`	Bad Request	Missing required field, invalid email, prompt too long, files not accepted.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	Key suspended/revoked, IP not allowed, oracle not in your allowed list, oracle not API-enabled.
`404`	Not Found	Oracle slug does not exist or is inactive.
`429`	Rate Limited	Daily or monthly request limit exceeded.
`500`	Server Error	Internal error — retry the request. If persistent, contact the admin.

7. Rate Limits

Each API key has two configurable limits:

Daily limit — resets at midnight UTC
Monthly limit — resets on the 1st of each month

Current remaining allowance is included in every successful response under rate_limit. When a limit is reached, the API returns 429 with details.

There is also a global rate limit of 60 requests per minute per IP address as a safety measure.

8. Examples

cURL

curl -X POST /api/v1/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: os_live_YOUR_KEY_HERE" \
  -d '{
    "appname": "vedic-oracle",
    "email": "user@example.com",
    "prompt": "I was born on 15 March 1990 at 14:30 in Mumbai. What does my chart say about career?"
  }'

JavaScript (fetch)

const response = await fetch('/api/v1/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'os_live_YOUR_KEY_HERE',
  },
  body: JSON.stringify({
    appname: 'vedic-oracle',
    email: 'user@example.com',
    prompt: 'Born 15 March 1990, 14:30, Mumbai. Tell me about my career.',
  }),
});

const data = await response.json();
console.log(data.response);

Python (requests)

import requests

resp = requests.post(
    '/api/v1/query',
    headers={'x-api-key': 'os_live_YOUR_KEY_HERE'},
    json={
        'appname': 'vedic-oracle',
        'email': 'user@example.com',
        'prompt': 'Born 15 March 1990, 14:30, Mumbai. Career analysis please.',
    }
)

data = resp.json()
print(data['response'])

With File Attachment

import base64, requests

with open('palm.jpg', 'rb') as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    '/api/v1/query',
    headers={'x-api-key': 'os_live_YOUR_KEY_HERE'},
    json={
        'appname': 'palm-reader',
        'email': 'user@example.com',
        'prompt': 'Please analyse my palm lines.',
        'files': [{'mimeType': 'image/jpeg', 'base64': img_b64}]
    }
)

print(resp.json()['response'])

OccultSanctum API — Built with ❤️ for astrologers and developers.