Authentication

API keys

Every request must include your API key in the X-API-Key header:

curl https://api.halal.sh/v1/instruments/AAPL/compliance \
  -H "X-API-Key: hsh_sandbox_your_key"

Keys are prefixed by environment:

hsh_sandbox_: sandbox keys (free, curated universe)
hsh_live_: live keys (the Plus plan, full universe)

Create and revoke keys from your API dashboard.

Live keys come with halal.sh Plus and are for your own use: research, automations, and internal workflows. To build a product on halal.sh, see the developer plans.A live key’s access follows your active subscription, not the moment the key was minted. If Plus lapses, existing hsh_live_ keys keep working but fall back to the sandbox universe and sandbox rate limits, and out-of-universe symbols start returning 403 sandbox_restricted. Renewing restores full access within five minutes; there is no need to mint a new key.

Treat your API key like a password. Never ship it in client-side code, a public repository, or a browser request. Always call the API from your backend.

The sandbox

Sandbox keys (hsh_sandbox_) return real data with the exact same response schema as production, scoped to a curated set of instruments:

	Symbols
Stocks	AAPL, MSFT, NVDA, GOOGL, JPM, GS, META, TSLA, JNJ, AMZN
ETFs	SPY, HLAL

These cover every compliance state (compliant AAPL, non-compliant JPM and GS) and a range of sectors, so you can build and test against each path. Requesting any other symbol returns 403 sandbox_restricted. Filter-based screening (/screen without symbols) also requires an active Plus plan. The same scope applies to any caller without an active paid plan: a sandbox key, a live key on a lapsed subscription, or a signed-in session on Free.

Rate limits

Limits follow the caller’s current plan, not their credential type.

Plan	Requests / day	Requests / minute	Evidence packets / month
Free (sandbox key, lapsed live key, or signed-in Free session)	100	10	10
Plus (live key or signed-in Plus session)	2,000	120	Unlimited
Enterprise	Custom	Custom	Unlimited

Every response includes your current limit state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-06-04T00:00:00.000Z

When you exceed a limit, the API returns 429 with a Retry-After header and a retry_after field (seconds):

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily request limit (100) exceeded. Resets at midnight UTC.",
    "retry_after": 3600
  },
  "meta": { "request_id": "req_abc123" }
}

The daily window resets at midnight UTC.

Error handling

Every error uses the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "No instrument found for symbol 'XYZ'."
  },
  "meta": { "request_id": "req_abc123" }
}

HTTP	`code`	Meaning
400	`bad_request`	Invalid parameters
401	`unauthorized`	Missing or invalid API key
403	`sandbox_restricted`	Symbol or feature outside the sandbox universe (no active paid plan)
404	`not_found`	Instrument or resource not found
429	`rate_limit_exceeded`	Too many requests
503	`service_unavailable`	Temporary outage, retry with backoff
500	`internal_error`	Server error, retry with backoff

Always log meta.request_id. It uniquely identifies the request and speeds up support.

Response envelope

Every success response has the same shape:

{
  "data": { "…": "…" },
  "meta": {
    "request_id": "req_abc123",
    "as_of": "2026-06-03T12:00:00.000Z",
    "methodology": "aaoifi-ss21@2026.1"
  }
}

meta.methodology is present on compliance-bearing responses and identifies the exact methodology version used. See Methodology versioning.

Versioning and stability

The API is versioned in the URL path (/v1). Within a version we guarantee:

no fields are removed or renamed,
no field types change,
no URL structure changes.

We may add fields, endpoints, optional parameters, and enum values within a version. Design your client to ignore unknown fields and to treat an unrecognised status as pending. Breaking changes ship as a new version (/v2) with a migration guide and a deprecation window for the previous one.

Support

Stuck, or seeing something that looks wrong? Contact us, and include the meta.request_id of any failing request so we can trace it.

Getting Started

Core Concepts

Guides

API keys

The sandbox

Rate limits

Error handling

Response envelope

Versioning and stability

Support

​API keys

​The sandbox

​Rate limits

​Error handling

​Response envelope

​Versioning and stability

​Support

API keys

The sandbox

Rate limits

Error handling

Response envelope

Versioning and stability

Support