Intelligence API

These endpoints use AI. Their output is a proposal for an advocate to read, never advice, and every answer points to the page or paragraph it came from. All need the scope ai:run. Prices are in credits (1 credit is ₹1 before GST); see pricing for how a firm on a paid seat plan pays the wallet rate and everyone else pays the listed price.

• Test mode returns fixed sample output marked "sandbox": true. No AI runs, nothing is charged, and the job flow and events work the same.
• Batch: send "mode": "batch" to POST /records/read for half the list price. It always runs in the background as a job. No other endpoint takes it: they answer 400 batch_not_supported.
• Your own model key: if your firm has added its own key in the app, a call costs 40% of the list price.
• Files go as multipart/form-data. Each file is at most 50 MB and one call at most 500 pages (400 too_many_pages). There are no URLs: you upload the file.

#Now, or as a job

A small call answers in the request with 200. A big one is accepted with 202 and a job you read later.

Call	Answers now	Becomes a job
POST /ocr	Up to 10 pages	More than 10 pages
POST /records/read	Up to 10 pages in all	More than 10 pages, or "mode": "batch"
POST /records/digest	Never	Always
POST /translate with text	Up to 2 pages (1 page is 2,000 characters)	More than 2 pages
POST /translate with a file	Never	Always
POST /research/answers, POST /drafts, GET /orders/{id}/summary	Always	Never

#Jobs

A job answer is 202 with status: queued:

{
  "object": "job",
  "id": "job_7hPz2KmV9aXq4Ld6Rs1TnE8c",
  "kind": "ocr",
  "status": "queued",
  "pages": 42,
  "batch": false,
  "credits": 0,
  "created_at": "2026-12-01T10:20:00+05:30",
  "completed_at": null
}

kind is ocr, record_read, record_digest or translation. Wait for the job.completed or job.failed event on your webhook, or poll GET /jobs/{id} (free; the job is visible only to its own account and mode, else 404 job_not_found). status goes queued, processing, then completed or failed.

curl https://adv.heliosynctech.com/api/v1/jobs/job_7hPz2KmV9aXq4Ld6Rs1TnE8c -H "Authorization: Bearer $AOS_KEY"

A completed job adds result, the same object a small call answers with, and completed_at. pages is then the pages actually processed, and credits what was charged. A failed job adds error.message, and is free. A job from a test key carries "sandbox": true.

Files and privacy. An uploaded file is your firm's data. It is kept on a private disk, never served to anyone, and deleted as soon as a call that answers now has answered. A job's files are deleted after 7 days. Under the Digital Personal Data Protection Act, 2023, your firm is the data fiduciary for the records you upload; Advocate OS processes them for you as your processor, only to do the work you asked for.

#Read a scan (OCR)

POST /ocr · ₹0.40, then ₹0.35 from 1,00,000 a month per page

Turn a PDF, PNG or JPEG into text, page by page. Field file.

curl -X POST https://adv.heliosynctech.com/api/v1/ocr \
  -H "Authorization: Bearer $AOS_KEY" -H "Idempotency-Key: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c99" \
  -F "file=@plaint.pdf"

{
  "object": "ocr",
  "pages": [
    { "page": 1, "text": "IN THE SANDBOX HIGH COURT\nSample text of page 1 of 2.", "legibility": "clear", "notes": [] },
    { "page": 2, "text": "IN THE SANDBOX HIGH COURT\nSample text of page 2 of 2.", "legibility": "clear", "notes": [] }
  ],
  "sandbox": true
}

legibility says how readable the page was (clear, or worse); notes says what could not be read. Read a poorly legible page by eye.

#Read a record

POST /records/read · ₹0.15 per page · batch for half

Read a case file the way a junior would. Send 1 to 20 PDFs as files[], one per document, and optionally matter, a line on what the record is about (it helps spot a paper of another matter). You get one record_document per file, labelled D1, D2 … in upload order: a card (what the document is) and the facts in it, each with the page it stands on. Code checks that a quote and an amount really are on that page; a fact it cannot check is flagged.

curl -X POST https://adv.heliosynctech.com/api/v1/records/read -H "Authorization: Bearer $AOS_KEY" \
  -F "files[]=@notice.pdf" -F "files[]=@reply.pdf" -F "matter=Recovery suit, Sandbox Lender v. Sharma"

{
  "object": "record",
  "documents": [
    {
      "object": "record_document",
      "document": "D1",
      "name": "notice",
      "pages": 3,
      "card": { "kind": "letter", "date": "2026-01-15", "from": "Sandbox Lender Finance Ltd", "to": "Aarav Sharma", "ref_no": "SLF/2026/1", "subject": "Demand for repayment", "summary": "A sample card: the lender demands repayment of the loan within 15 days.", "asks": "Repay ₹4,50,000 within 15 days.", "decides": "", "other_matter": false, "other_matter_why": "" },
      "facts": [
        { "type": "demand", "actor": "Sandbox Lender Finance Ltd", "date": "2026-01-15", "amount": "450000", "clause": "", "text": "The lender demanded repayment of ₹4,50,000 within 15 days.", "quote": "", "flags": [], "pages": [ { "ref": "D1p1", "page": 1 } ] }
      ]
    }
  ],
  "sandbox": true
}

A page is cited as D1p1: document 1, page 1. More than 10 pages, or "mode": "batch", gives a job.

#Digest a record

POST /records/digest · ₹0.25 per page

The same upload as a record read, plus a short digest of the whole record. Always a job. The result is a record_digest: the documents, the cards the digest cites (C1 is document D1), the digest in Markdown citing cards as [C1], the parties and the threads of the story, each with the cards it rests on.

{
  "object": "record_digest",
  "documents": [ { "object": "record_document", "document": "D1", "name": "notice", "pages": 3 } ],
  "cards": { "C1": "D1" },
  "digest": "A sample digest: the lender demanded repayment [C1]; no reply is on record.",
  "parties": [ { "name": "Sandbox Lender Finance Ltd", "role": "lender", "cards": ["C1"] } ],
  "threads": [ { "title": "Repayment demand", "cards": ["C1"], "story": "The lender demanded repayment [C1].", "open_items": [ { "text": "Whether the borrower replied.", "cards": ["C1"] } ] } ],
  "sandbox": true
}

(documents is shortened to the document's name here; each is a full record_document, as above.)

#Summarise an order

GET /orders/{id}/summary · ₹2.50 per order

A short summary of an order from court data: what the court decided, the next date and the directions. If the order has already been summarised, the stored summary is returned ("reused": true) with no AI run, and it costs nothing. If not, we summarise it once and keep it. An order whose text has not been read yet gives 409 order_not_read: fetch it with GET /orders/{id} first.

curl https://adv.heliosynctech.com/api/v1/orders/ord_4821/summary -H "Authorization: Bearer $AOS_KEY"

{
  "object": "order_summary",
  "order_id": "ord_4821",
  "reused": false,
  "summary": ["The court heard the application and listed the matter for arguments."],
  "outcome": "adjourned",
  "next_date": "2026-12-15",
  "next_purpose": "Arguments",
  "directions": [ { "who": "Respondent", "what": "File reply", "due_date": "2026-12-08", "due_text": "within one week" } ],
  "coram": "Hon'ble Justice R. K. Menon",
  "language": "English",
  "notes": [],
  "digested_at": "2026-12-01T10:20:00+05:30"
}

#Translate

POST /translate · ₹2 per page (1 page = 2,000 characters)

Translate text or a PDF into English or Hindi, page by page.

Field	Meaning
text or file	JSON text (up to 2 pages answers now), or a multipart PDF file (always a job). Not both.
to	en or hi. Required.
from	Optional ISO 639 code of the source language, such as ta.

curl -X POST https://adv.heliosynctech.com/api/v1/translate \
  -H "Authorization: Bearer $AOS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d00" \
  -d '{ "text": "The matter is listed for hearing on 2026-12-15.", "to": "hi" }'

{
  "object": "translation",
  "to": "hi",
  "pages": [ { "page": 1, "source_language": "English", "text": "[Sample translation into Hindi of page 1]" } ],
  "notes": [],
  "sandbox": true
}

A page the model did not return has "missing": true.

#Answer a research question

POST /research/answers · ₹25 per answer

Ask a question in plain English. The answer is written from judgments and bare acts in the library, and every statement points to the paragraph or section it rests on. A statement we cannot support is left out.

Field	Meaning
question	Your question, 8 to 1,000 characters.
court	Optional: only judgments whose court name contains this.

curl -X POST https://adv.heliosynctech.com/api/v1/research/answers \
  -H "Authorization: Bearer $AOS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e11" \
  -d '{ "question": "Is readiness and willingness a continuing requirement in a suit for specific performance?", "court": "Supreme Court" }'

{
  "object": "research_answer",
  "question": "Is readiness and willingness a continuing requirement in a suit for specific performance?",
  "answer": {
    "items": [
      { "text": "Yes. The plaintiff must show readiness and willingness from the date of the agreement to the date of the hearing.", "sources": ["P1"], "unverified": [] }
    ],
    "unanswerable": false,
    "notes": []
  },
  "sources": {
    "P1": { "type": "paragraph", "judgment_id": 18234, "paragraph_id": 902114, "label": "Para 12", "title": "Sample Buyer v. Sample Seller", "citation": "2023 INSC 512", "court": "Supreme Court of India", "date": "2023-05-18", "text": "Readiness and willingness is a continuing requirement…" }
  }
}

sources keys are P1… for judgment paragraphs and S1… for sections of an act. unverified lists a citation in the text that no source carries: check it by hand. If the library has nothing on the question you get 404 no_material and pay nothing; if every statement lacked a source, the answer is empty and free. Open a source with GET /judgments/{judgment_id}, and run the citator before you rely on one. See RAG over judgments.

#Draft a document

GET /drafts/blueprints · free · POST /drafts · ₹10 per draft

GET /drafts/blueprints lists the kinds of document and the facts each needs, as { "object": "blueprint", "key", "name", "group", "kind", "summary", "ai", "sides", "fields": [ { "name", "label", "type", "required", "help" } ] }. The key legal_notice is "Legal notice", with the required facts subject, facts, demand and days.

POST /drafts writes a first draft in Indian court format. The model writes the prose; code writes the formal parts. The draft also opens in the firm's Drafting Studio for review. It is a proposal for an advocate to review: anything the facts did not supply is left as a visible blank or a [VERIFY] mark, never invented.

Field	Meaning
blueprint	A key from GET /drafts/blueprints. An unknown one gives 400 unknown_blueprint.
facts	An object of the blueprint's fields by name. A required one that is missing gives 400 missing_fact and names it.
language	en (default) or hi.
parties	Optional: { "first": [ { "name", "details" } ], "second": [ … ] }.

curl -X POST https://adv.heliosynctech.com/api/v1/drafts \
  -H "Authorization: Bearer $AOS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f22" \
  -d '{ "blueprint": "legal_notice", "facts": { "subject": "Recovery of ₹5,00,000 due on a dishonoured cheque", "facts": "Cheque no. 004512 dated 2026-09-20 was returned unpaid on 2026-10-02 for insufficient funds.", "demand": "Pay ₹5,00,000 within the time below.", "days": 15 } }'

{
  "object": "draft",
  "id": 311,
  "blueprint": "legal_notice",
  "title": "Legal notice",
  "language": "en",
  "status": "ready",
  "html": "<p><strong>Legal notice</strong></p><p>…</p>",
  "warnings": []
}

(A test key returns "id": "drf_sandbox", a fixed sample html and "sandbox": true.) html is the draft; warnings lists what to check. See draft a petition for the whole flow.