# Advocate OS developer platform

> The Advocate OS API gives software and AI agents Indian court data (eCourts cases by CNR, cause lists, orders), judgments with paragraph citations, bare acts, limitation, litigation-check reports, case watches with signed webhooks, and a firm's own workspace. Prices are in rupees. A free sandbox High Court needs no court access and costs nothing.

API base: https://adv.heliosynctech.com/api/v1. OpenAPI: https://adv.heliosynctech.com/api/openapi.json. MCP server: https://adv.heliosynctech.com/mcp. Dates are yyyy-MM-dd (IST).

## For coding agents

- Start with a test key (`aos_test_…`, Firm › Developers) and the sandbox: it is free and never reads a court. The CNR `SBXX010000012026` is a pending case; the other sandbox CNRs are listed at https://adv.heliosynctech.com/developers/sandbox.md.
- Read the `doc_url` of any error response: it links to https://adv.heliosynctech.com/developers/errors#code, which says how to fix that code.
- Send an `Idempotency-Key` on every POST; send `AOS-Version` to pin behaviour. Read `AOS-Credits-Charged` to see what a call cost.
- Configure with the environment variables `AOS_API_BASE` and `AOS_KEY`; never write a host or a key into code.
- Every page below is also a plain Markdown file; https://adv.heliosynctech.com/developers/llms-full.txt has all of them in one file.

## Start here

- [Developer platform](https://adv.heliosynctech.com/developers/index.md): Build on Indian court data. Cases by CNR, cause lists, orders, judgments, reports and watches over one JSON API, with a free sandbox. Priced in rupees.
- [Quickstart](https://adv.heliosynctech.com/developers/quickstart.md): Sign up, make a test key and read your first case from the sandbox High Court in curl, TypeScript, Python or PHP, in under five minutes.
- [Authentication](https://adv.heliosynctech.com/developers/authentication.md): How API keys work. Test and live keys, scopes, sending a key, rotating one without downtime, and reading your account and usage.
- [Sandbox](https://adv.heliosynctech.com/developers/sandbox.md): The Sandbox High Court. Test CNRs that give a pending case, a disposed case, daily orders, an outage and a masked case, plus the sandbox date and reset.

## Concepts

- [Rate limits](https://adv.heliosynctech.com/developers/rate-limits.md): Trust tiers T0 to T3, requests a second and daily spend limits, the RateLimit headers on every response, and how to back off when you get a 429.
- [Errors](https://adv.heliosynctech.com/developers/errors.md): Every error type and code the API returns, what causes it, and how to fix it. Each code has its own link, which is the doc_url in the error body.
- [Pricing](https://adv.heliosynctech.com/developers/pricing.md): What an API call costs in rupees. Plans, free credits each month, the price of every endpoint, volume steps, AI pricing, GST and how a charge is taken.
- [Webhooks](https://adv.heliosynctech.com/developers/webhooks.md): Get a signed HTTP call when a case changes. Make an endpoint, verify the signature in TypeScript, Python, PHP or curl, handle retries and test locally.
- [Events](https://adv.heliosynctech.com/developers/events.md): The event log and every event type, case.updated to job.failed, with the exact data each one carries and how to read missed events.
- [Idempotency](https://adv.heliosynctech.com/developers/idempotency.md): Send an Idempotency-Key on every POST so a retry never runs twice and never bills twice. How long keys last and what to do on a conflict.
- [Versioning](https://adv.heliosynctech.com/developers/versioning.md): The AOS-Version header, how your account is pinned to a dated version, what counts as a breaking change, and how to upgrade safely.
- [Pagination](https://adv.heliosynctech.com/developers/pagination.md): How lists work. The list object, limit up to 100, the cursor parameter, next_cursor, and a loop that reads every page in TypeScript and Python.

## API reference

- [Court data API](https://adv.heliosynctech.com/developers/court-data.md): Find cases by CNR, party or number, read status and orders, check cause lists, match CNRs to a day and work out court fee. Prices and examples.
- [Research and law API](https://adv.heliosynctech.com/developers/research-and-law.md): Search judgments, read them by paragraph, check citations, read a citator, look up bare act sections, map IPC to BNS and count limitation in code.
- [Reports API](https://adv.heliosynctech.com/developers/reports.md): Order a litigation check or a due-diligence report on a person or company, get a webhook when it is done, and download a PDF with a verify QR.
- [Monitoring API](https://adv.heliosynctech.com/developers/monitoring.md): Watch a case or a person and get an event when the next date moves, an order lands, a case is listed or a new case is filed. Prices per month.
- [Intelligence API](https://adv.heliosynctech.com/developers/intelligence.md): Read scanned records, summarise an order, translate, answer a research question with paragraph citations and draft a petition. Jobs, batch mode, prices.
- [Workspace API](https://adv.heliosynctech.com/developers/workspace.md): Read your own firm's matters, hearings, deadlines, tasks, documents and drafts, and add tasks and notes. For your dashboards and your own AI agents.

## Tools

- [SDKs](https://adv.heliosynctech.com/developers/sdks.md): Official TypeScript, Python and PHP libraries. Install, set AOS_API_BASE and AOS_KEY, make a call, handle errors, retries and verify webhooks.
- [CLI](https://adv.heliosynctech.com/developers/cli.md): The aos command line. Log in, look up a case by CNR, search judgments, forward webhook events to localhost with aos listen, trigger sandbox events.
- [MCP server](https://adv.heliosynctech.com/developers/mcp.md): Connect Claude, ChatGPT or Cursor to your firm's matters, hearings, deadlines, documents and the judgment library through the Advocate OS MCP server.
- [Build with AI](https://adv.heliosynctech.com/developers/build-with-ai.md): A copy-paste prompt for Claude Code or Cursor that installs the SDK, reads AOS_API_BASE and AOS_KEY from the environment, and makes a sandbox call.

## Guides

- [Litigation check for lenders](https://adv.heliosynctech.com/developers/litigation-check-for-lenders.md): Check a borrower or guarantor for court cases before you lend. Order the report, wait for the webhook, read the matches and keep the PDF.
- [Case watch with webhooks](https://adv.heliosynctech.com/developers/case-watch-with-webhooks.md): Watch a case by CNR and get a signed webhook when its next date changes or an order lands. Build and test it end to end in the sandbox.
- [RAG over judgments with citations](https://adv.heliosynctech.com/developers/rag-over-judgments-with-citations.md): Build a research assistant whose answers cite a judgment and a paragraph. Search, read by paragraph, check citations and drop overruled cases.
- [Draft a petition](https://adv.heliosynctech.com/developers/draft-a-petition.md): Build a drafting flow. Work out limitation and court fee in code, find authorities with citations, then draft with the API for an advocate to review.
- [Firm dashboard with the workspace API](https://adv.heliosynctech.com/developers/firm-dashboard-with-workspace-api.md): Build a screen for the firm's own hearings, deadlines and tasks from the workspace API, on a server, with a firm key and without exposing it.
- [An AI agent over MCP](https://adv.heliosynctech.com/developers/ai-agent-over-mcp.md): Give an AI agent your firm's matters through MCP and public court data through the API. Tool loop in Python, safe defaults and prompt-injection rules.

## Releases

- [Changelog](https://adv.heliosynctech.com/developers/changelog.md): What changed in the Advocate OS API, by dated version. The first release is 2026-12-01. Read this before you change your AOS-Version.

## Optional

- [API reference](https://adv.heliosynctech.com/developers/reference): every endpoint, generated from the OpenAPI document
- [llms-full.txt](https://adv.heliosynctech.com/developers/llms-full.txt): every page above in one file