Official documentation for integrating OSINT search and upstream proxies. This page covers authentication (API key and Firebase session), credit and daily quota consumption (UTC), per-key and global IP limits, CORS rules, allowed JSON shapes, response normalization, and a full HTTP error reference—aligned with the running server.
X-API-Version: 1Content-Type required where notedhttps://osintstar.vipusername · email · domain · phone · ip · hash · discord
free plan cannot call with an API key).osk_live_ + 48 hex chars). Store it server-side only.POST /api/search or POST /api/search/{type} with the appropriate auth headers.GET /api/usage using your Firebase ID token (not the OSINTSTAR API key).type values are fixed and validated server-side. Pick the type that matches your query; the upstream applies its own parsing rules and data sources.
Handles and screen names used across online services. Useful for correlating accounts across platforms.
Full email address. The upstream engine may match against breaches, leaks, and public sources.
Domain name or hostname (e.g. example.com). For infrastructure and web-presence intelligence.
Phone number in the format expected by the upstream backend (e.g. E.164 where supported).
IPv4 or IPv6 for approximate geolocation, ASN, and network metadata when available.
Cryptographic digests (e.g. MD5, SHA-1/256) for lookups against known sets or upstream tooling.
Numeric Discord ID or text identifier. On 400/422 the server automatically retries once as username.
{ "query", "type" } or an empty body (forwarded as-is after auth). Supports API key or Firebase Bearer (dashboard session).{ "query" }. Requires an API key only (ideal for server-to-server integrations).All paths are under your base URL. Billable routes charge one usage unit after authentication and before the upstream call (except /api/public/status and /api/usage).
| Method | Path | Auth | Usage | Notes |
|---|---|---|---|---|
| GET | /api/public/status | None | — | Maintenance, announcements, pricing |
| POST | /api/search | API key or Firebase Bearer | 1 | Optional JSON body; strict keys query + type |
| POST | /api/search/{type} | API key only | 1 | Body { "query" }; types: username, email, domain, phone, ip, hash, discord |
| POST | /api/stealer | API key only | 1 | Proxies JSON to upstream /api/stealer |
| GET | /api/get/* | API key only | 1 | Proxies GET upstream /api/…; max 10 segments |
| GET | /api/usage | Firebase Bearer | — | Daily UTC quota, bonus, plan |
API keys use the prefix osk_live_ followed by exactly 48 hexadecimal characters (normalized to lowercase). Send the key using either header:
x-api-key: <key>Authorization: Bearer <key> (same value as x-api-key—not a Firebase JWT)Keys are issued from the Dashboard; they may expire. Revoked or expired keys return 401.
x-api-key: osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxIf Authorization: Bearer is not a valid API key string, it is treated as a Firebase ID token. That path uses dashboard guards (free plan may call; paid API-key block does not apply). All other OSINT routes in the matrix require a valid API key.
Each successful authentication on a billable route consumes one usage unit from your account before the upstream request runs. Order: bonus credits (if any) are decremented first; otherwise the paid-plan daily UTC counter applies, or the lifetime counter for free. If neither has capacity, 402with a message like "No credits remaining for your plan."
The usage unit is charged even when the upstream returns 4xx/5xx—design retries accordingly.
| Plan | Limit (UTC / lifetime) | API key access |
|---|---|---|
| free | 10 usage units (lifetime counter) | 403 — plan does not include API key access |
| basic | 100 / UTC day | Allowed |
| medium | 250 / UTC day | Allowed |
| pro | 2000 / UTC day | Allowed |
Disabled account, suspension, or expired plan → 403 with a specific error string.
Sliding window ~60 requests/minute per key (in-process; multiple instances multiply effective throughput).
Edge middleware caps all API requests per client IP (default ~360/min, env-tunable). Exceeded → 429 with Retry-After 60.
Content-Length over ~1 MB → 413 where pre-checked. Typed search JSON parsing caps at ~256 KB.
Proxy aborts around 28s → 504 on generic search; other routes may surface upstream errors differently.
Repeated invalid payloads from an IP can return 403 with Retry-After.
Stricter per-IP limit on auth routes in addition to the global cap.
Origin header must use an allowlisted origin (app URL, localhost in dev, configured public URLs). Otherwise middleware may return 403.OPTIONS preflight is supported; allowed headers include Content-Type, Authorization, x-api-key.Origin) skip browser CORS checks but still hit global IP limits.No authentication. Returns JSON: maintenance object, up to 3 active announcements (newest first), and sanitized pricing fields when configured.
curl -sS "https://osintstar.vip/api/public/status"{
"maintenance": { "enabled": false, "message": null, "updatedAt": null },
"announcements": [ { "id": "…", "title": "", "message": "", "createdAt": 0 } ],
"pricing": { "basic": 9.99, "medium": 19.99, "pro": 49.99, "currency": "USD" }
}Proxies to upstream POST /api/search. Body optional. If non-empty, Content-Type must be application/json and the object must be strict: only query (string, max 4000) and type (enum: username, email, domain, phone, ip, hash, discord)—no extra keys.
Empty body is forwarded after auth (still consumes one usage unit). Invalid JSON / wrong Content-Type / extra keys → 400 or 415; validation errors may include an issues object (Zod flatten).
curl -X POST https://osintstar.vip/api/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"target@example.com","type":"email"}'const res = await fetch("https://osintstar.vip/api/search", {
method: "POST",
headers: {
"x-api-key": process.env.OSINTSTAR_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "acme.com", type: "domain" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error ?? "Request failed");import requests
r = requests.post(
"https://osintstar.vip/api/search",
headers={
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
json={"query": "john_doe", "type": "username"},
timeout=30,
)
r.raise_for_status()
print(r.json())The URL segment type is one of: username, email, domain, phone, ip, hash, discord (case insensitive). Body must be exactly { "query": "<1..4000 chars>" } (strict JSON).
Discord: if upstream returns 400 or 422 for type discord, the server retries once with type username.
curl -X POST https://osintstar.vip/api/search/email \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"target@example.com"}'Proxies the raw body to upstream POST /api/stealer. Content-Type: application/json is required. Non-empty bodies must be valid JSON and satisfy internal depth/size checks.
curl -X POST https://osintstar.vip/api/stealer \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"example":"payload"}'GET /api/<segments>.[a-zA-Z0-9_.-]+; . and .. are rejected; 1–10 segments.[a-zA-Z0-9_]+; values are passed through.curl "https://osintstar.vip/api/get/breach/check?email=target@example.com" \
-H "x-api-key: YOUR_API_KEY"Returns usage for the signed-in user: plan, daily limit (or lifetime for free), current consumption, remaining allowance, and bonus credits. Requires Authorization: Bearer <Firebase ID token> (same token the web app uses after login), not the OSINTSTAR API key.
Dedicated rate limit: ~30 requests/minute per user account. Does not consume search usage units.
curl -sS "https://osintstar.vip/api/usage" \
-H "Authorization: Bearer FIREBASE_ID_TOKEN"{
"planId": "basic",
"dailyLimit": 100,
"usedToday": 12,
"remaining": 88,
"dayKey": "2026-04-23",
"bonusCredits": 0
}For free, dayKey is "lifetime" and usedToday reflects the lifetime total counter.
If upstream returns JSON with a top-level results property, the body is normalized to { "results": … } while preserving the HTTP status. Other JSON objects are returned as-is. Non-JSON bodies keep original bytes and Content-Type.
X-API-Version: 1Cache-Control: no-store on API routesRetry-After (429, some 403s)JSON errors usually include { "error": "…" }. Some 400s add issues (Zod). Maintenance returns { "error": "Maintenance", "message": "…" }.
| Code | When |
|---|---|
| 400 | Invalid body, search type, proxy path; malformed JSON; payload too nested. |
| 401 | Missing credentials; invalid or expired API key; invalid Firebase token. |
| 402 | No credits / daily quota / bonus left. |
| 403 | Free plan API blocked; disabled/suspended account; expired plan; origin blocked (browser); IP abuse cooldown. |
| 413 | Request body too large (Content-Length). |
| 415 | Content-Type must be application/json where required. |
| 429 | Per-key search limit or global per-IP API limit—honor Retry-After. |
| 500 | Unhandled server error. |
| 502 | Upstream fetch failed (e.g. generic search). |
| 503 | Maintenance mode enabled. |
| 504 | Upstream request timed out. |
When enabled on your profile, search queries may be stored server-side (endpoint name, query, type, HTTP status, timestamp). You can control this from the Dashboard. Billing is unchanged: billable routes still consume one usage unit per call as described above.
Documentation reflects application behavior at build time; environment variables may tune rate-limit values in production.