Developers

Eligibility with sources, in one API call

This page is for programmers. Not a developer? Check your eligibility here instead. An API lets other software ask Niyam questions. Read endpoints work without a key at a low rate limit. Create a free key for higher limits and to run agent jobs on your own documents. Every answer carries the clause behind it.

Step 1
Create a key below (shown once)
Step 2
Call POST /api/v1/eligibility
Step 3
Show your users the reason and the source

Create a free API key

curl

curl -X POST https://34-227-135-194.sslip.io/api/v1/eligibility \
  -H "Authorization: Bearer $NIYAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"age": 34, "gender": "female", "annual_family_income": 240000, "date": "2024-08-01"}'

Python

import httpx

r = httpx.post(
    "https://34-227-135-194.sslip.io/api/v1/eligibility",
    headers={"Authorization": f"Bearer {NIYAM_KEY}"},
    json={"age": 34, "gender": "female", "annual_family_income": 240000},
)
for scheme in r.json()["results"]:
    print(scheme["name"], scheme["eligible"], scheme["monthly_benefit_inr"])
    for reason in scheme["reasons"]:
        src = reason["source"]
        print("  ", reason["met"], reason["rule"], "<-", src["document"]["code"], "p.", src["page"])

JavaScript

const r = await fetch("https://34-227-135-194.sslip.io/api/v1/eligibility", {
  method: "POST",
  headers: { Authorization: `Bearer ${NIYAM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ age: 34, gender: "female", annual_family_income: 240000 }),
});
const { results, disclaimer } = await r.json();

Reference

Endpoints

Send keys as Authorization: Bearer niyam_live_.... Responses include X-RateLimit-Limit and X-RateLimit-Remaining.

Method	Path	Auth	What it does
POST	/api/v1/eligibility	none or key	Eligibility for every covered scheme, with the amount, each reason, and the source clause behind each reason.
GET	/api/v1/schemes	none or key	Covered schemes with their last change date.
GET	/api/v1/schemes/{id}/rules?at=YYYY-MM-DD	none or key	The rules of a scheme on any date, each with its source and, for agent changes, the pull request and the Entire checkpoint (the saved record of which AI agent, model and session wrote the rule).
GET	/api/v1/schemes/{id}/history	none or key	Every change over time, oldest first.
GET	/api/v1/changes	none or key	Recent rule changes in plain language.
POST	/api/v1/documents	key (run scope) or 3 per day	Bring your own document: upload a PDF (file) or a link (url). Starts an agent job on a sandbox branch.
GET	/api/v1/jobs/{id}	none or key	A job: state, changes, verification, decision, cost, trace id, pull request, checkpoint, events.
GET	/api/v1/jobs/{id}/events	none	Server-sent events: each step of a running job as it happens.
POST	/api/v1/keys	none	Create a free key (shown once, hashed on our side).
GET	/api/v1/usage	key	Your calls, jobs and cost per day.
POST	/api/v1/webhooks	key	Subscribe a public https URL to rule.changed, rule.change_proposed or job.needs_human. Returns a signing secret once.
GET	/api/v1/why?file=&line=	none	Line-level provenance from Entire: the agent, model, session and checkpoint behind one rulebook line.
GET	/api/v1/status	none	Source health, running jobs, tracing status.
GET	/api/v1/evals	none	All evaluation results, per version and per case.

Example response

JSON

{
  "as_of": "2024-08-01",
  "rulebook_version": "9ddb04d",
  "results": [{
    "scheme_id": "mh.ladki_bahin",
    "name": "Mukhyamantri Majhi Ladki Bahin Yojana",
    "eligible": true,
    "monthly_benefit_inr": 1500,
    "reasons": [{
      "rule": "Aged 21 to 65 (completed years)", "met": true,
      "source": {
        "page": 2, "clause": "4(3)",
        "quote": "किमान वयाची २१ वर्षे पूर्ण व कमाल वयाची ६५ वर्ष पूर्ण होईपर्यंत.",
        "quote_en": "Minimum age 21 years completed and maximum age until 65 years are completed.",
        "document": { "code": "202407031335114330",
                      "url": "https://gr.maharashtra.gov.in/Site/Upload/Government%20Resolutions/Marathi/202407031335114330.pdf" },
        "provenance": { "pr_url": "https://github.com/usv240/niyam-rulebook/pull/2",
                        "checkpoint_id": "01M4JDH944E4HPRCA4WKDJTFN7" } }
    }]
  }],
  "disclaimer": "Information only. Final eligibility is decided by the government department."
}

Errors

Errors are JSON: {"error": {"code", "message", "docs_url"}}. Codes include invalid_key, rate_limited (with Retry-After), daily_limit, personal_data_rejected (a value looked like an Aadhaar or phone number), not_pdf, too_large.

Limits

No key: 30 requests per minute, 3 documents per day.
Free key: 120 requests per minute, 20 documents per day.
Navigator plan: 600 requests per minute, 200 documents per day (see the business plan).

Privacy by design

The API never needs names, Aadhaar numbers or phone numbers, and rejects values that look like them. Eligibility requests are not stored, only counted.

Webhooks

Get told when a rule changes

Niyam POSTs a JSON event to your https URL when a change is proposed, merged, or needs a human. Each request carries X-Niyam-Event and X-Niyam-Signature (HMAC-SHA256 of the raw body with your secret). Internal and private addresses are refused.

Python: verify a webhook

import hashlib, hmac

def is_from_niyam(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

For AI assistants

Add Niyam to Claude, Cursor or any MCP client

Six tools: check_eligibility, explain_rules, rule_history, list_schemes, recent_changes and submit_document. Your assistant then answers with current rules and their sources, instead of guessing.

shell

claude mcp add niyam --env NIYAM_API_BASE=https://34-227-135-194.sslip.io -- \
  uvx --from "git+https://github.com/usv240/niyam#subdirectory=agent" niyam-mcp

Open source

Run your own copy

Everything is open: the agent, the API, the website and the rulebook. usv240/niyam and usv240/niyam-rulebook.

shell

git clone https://github.com/usv240/niyam && cd niyam/agent
uv venv && uv pip install -e . && uvicorn niyam.api:app --port 8000