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 type:

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

Create and revoke keys from your API dashboard.

Live keys come with the Plus plan and with the Developer plan. On Plus they’re for your own use: research, automations, and internal workflows. To show halal.sh results to the users of your product, you need the Developer plan, a separate subscription with a commercial license and higher limits. See Licensing.A live key’s access depends on the plans your account has now, not on when you created the key. If the Developer plan ends while you have Plus, your keys keep the full universe at the Plus limits. With neither plan active, existing hsh_live_ keys keep working but fall back to the sandbox universe and its limits, and out-of-universe symbols start returning 403 sandbox_restricted. When you renew, full access returns within five minutes on the keys you already have.

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

The sandbox

Sandbox keys (hsh_sandbox_) return real data in the same response schema as live keys, for these instruments:

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

They include both determinations (AAPL is compliant, JPM and GS are non-compliant) across a range of sectors, so you can build and test both paths. All 12 are analyzed, so no sandbox stock comes back pending. Any other symbol returns 403 sandbox_restricted. Filter-based screening (/screen without symbols) needs Plus or the Developer plan. The same scope applies to every sandbox key, and to a live key or a signed-in session whose account has neither Plus nor the Developer plan.

Rate limits

A sandbox key always has the sandbox limits. A live key or a signed-in session has the limits of your account’s current plan, and with the Developer plan that’s the Developer limits, whether or not you also have Plus.

Plan	Requests / day	Requests / minute	Evidence Packets / month
Sandbox (any sandbox key, or a live key or signed-in session without a paid plan)	100	10	10
Plus (live key or signed-in Plus session)	2,000	120	Unlimited
Developer (live key or signed-in Developer session)	10,000	300	Unlimited
Enterprise	Custom	Custom	Unlimited

Developer limits are per account: every live key, connected app and signed-in session on the account shares the same 10,000 requests a day and 300 a minute. Plus limits apply to each live key separately. Every response has your daily limit state in these headers:

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). When you are on the sandbox, the message also says what the Plus plan includes and costs, and upgrade gives your code the same offer as fields:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily limit of 100 requests reached. It resets at midnight UTC. The Plus plan includes up to 2,000 requests a day on every stock and ETF we cover, for $7 a month: https://halal.sh/plans?source=api_refusal. To show results in your own product, you need the Developer plan, at $99 a month: https://halal.sh/developers.",
    "retry_after": 3600,
    "upgrade": {
      "plan": "plus",
      "price_usd_monthly": 7,
      "url": "https://halal.sh/plans?source=api_refusal",
      "commercial_plan": "developer",
      "commercial_price_usd_monthly": 99,
      "commercial_url": "https://halal.sh/developers"
    }
  },
  "meta": { "request_id": "req_abc123" }
}

A 403 sandbox_restricted has the same upgrade object. The daily window resets at midnight UTC.

Error handling

Every error uses the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "Stock with identifier 'XYZ' not found"
  },
  "meta": { "request_id": "req_abc123" }
}

HTTP	`code`	Meaning
400	`bad_request`	Invalid parameters
401	`unauthorized`	Missing or invalid API key
403	`sandbox_restricted`	Outside the sandbox (no active paid plan): a symbol it doesn’t include, filter-based screening, or Evidence Packets past its 10 a month
403	`plan_required`	Requesting an analysis needs the Plus or Developer plan
404	`not_found`	Instrument or resource not found
409	`already_analyzed`	You asked for an analysis of a stock that already has one
409	`listing_not_active`	You asked for an analysis of a delisted or inactive listing
422	`no_filings`, `stale_filings`, `withheld`	We can’t analyze the stock you asked for; the reason is in `message`
429	`rate_limit_exceeded`	Too many requests
429	`analysis_limit_reached`	Your account’s on-demand analysis allowance is used up
503	`service_unavailable`	Temporary outage, retry with backoff
500	`internal_error`	Server error, retry with backoff

On the sandbox, a 403 sandbox_restricted and a 429 also have an upgrade object, so your code can show what full access costs:

Field	Meaning
`plan`	`plus`, the plan for your own use
`price_usd_monthly`	The Plus plan’s monthly price in US dollars
`url`	Where to get the Plus plan
`commercial_plan`	`developer`, the plan for showing results in your own product
`commercial_price_usd_monthly`	The Developer plan’s monthly price in US dollars
`commercial_url`	Where to get the Developer plan

A caller on a paid plan gets no upgrade. Log meta.request_id: it identifies the request, so we can trace it when you contact 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"
  }
}

Responses with a compliance result have meta.methodology, the exact methodology version behind it. 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 unrecognized status as pending. We will release breaking changes 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