kanoon.dev

Beta

The API for Indian Law.

Introduction

You can interact with the API through HTTP requests via our official Node.js library.

To install the official Node.js library, run the following command in your Node.js project directory:

pnpm install kanoon

Authentication

The Kanoon API uses API keys for authentication.

Remember that your API key is a secret! Do not share it with others or expose it in any client-side code (browsers, apps). Production requests must be routed through your own backend server where your API key can be securely loaded from an environment variable or key management service.

All API requests should include your API key in the Authorization HTTP header as follows:

Authorization: Bearer KANOON_API_KEY

Courts

This object represents the courts in the judicial wing of the Government of India. Use it to retrieve information about courts and cases.

The court object

This is an object representing a court.

string

The unique identifier for the court.

object

string

The object type, which is always court.

name

string

The name of the court.

The court object

{
  "id": "APHC01",
  "object": "court",
  "name": "Allahabad High Court"
}

List courts

Returns a list of courts.

GET
https://api.kanoon.dev/v1/courts

Query Parameters

limit

number

Optional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order

string

Optional

Sort order by the name of the objects. asc for ascending order and desc for descending order.

after

string

Optional

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

before

string

Optional

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

Returns

A list of court objects.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
const courts = await kanoon.courts.list();

console.log(courts);
}

main();

Response

[
  "object": "list",
  "data": [
    {
      "id": "APHC01",
      "object": "court",
      "name": "Allahabad High Court",
    },
    {
      "id": "HCBM01",
      "object": "court",
      "name": "Bombay High Court",
    },
    {...},
    {...},
  ]
]

Retrieve court

Retrieve a court.

GET
https://api.kanoon.dev/v1/courts/{court_id}

Path parameters

court_id

string

Required

The ID of the court to use for this request.

Returns

The court object matching the specified ID.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const court = await kanoon.courts.retrieve("APHC01");

  console.log(court);
}

main()

Response

{
  "id": "APHC01",
  "object": "court",
  "name": "Allahabad High Court"
}

Cases

This object represents a case in a court. Use it to retrieve information about cases.

The case object

This is an object representing a court.

string

The unique identifier of the case.

object

string

The object type, which is always court.case.

court_id

string

The ID of the court this case belongs to.

filed_at

string

The date the case was filed.

registered_at

string

The date the case was registered.

decided_at

string

The date the case was decided.

status

string

The status of the case.

type

string

The type of the case.

state

string

The state the case is in.

district

string

The district the case is in.

petitioners

string[]

The petitioners in the case.

respondents

string[]

The respondents in the case.

The case object

{
  "id": "JKHC01-003375-2023",
  "object": "case",
  "court_id": "JKHC01",
  "filed_at": "2023-07-15",
  "registered_at": "2023-07-15",
  "status": "in_progress",
  "type": "HCP",
  "state": "Jammu and Kashmir",
  "district": "Srinagar",
  "petitioners": [
    "Kaisar Ahmad Sheikh",
    "Mr. S.A. Hussain"
  ],
  "decided_at": null,
  "respondents": [
    "Union Territory of Jammu and Kashmir and Ors. (Home Department)"
  ]
}

List cases

Returns a list of cases for a given court.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases

Path parameters

court_id

string

Required

The ID of the court to use for this request.

Query parameters

limit

number

Optional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order

string

Optional

Sort order by the filed_at timestamp of the objects. asc for ascending order and desc for descending order.

after

string

Optional

before

string

Optional

filter

string

Optional

Filter by case status. Either in_progress or disposed.

Returns

A list of case objects.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const cases = await kanoon.courts.cases.list("JKHC01", {
    limit: 5,
    order: "desc",
  });

  console.log(cases);
}

main()

Response

{
  "object": "list",
  "data": [
    {
      "id": "JKHC01-003443-2023",
      "object": "case",
      "filed_at": "2023-07-19",
      "registered_at": "2023-07-19",
      "court_id": "JKHC01",
      "decided_at": null,
      "status": "in_progress",
      "type": "HCP",
      "state": "Jammu and Kashmir",
      "district": "Srinagar",
      "petitioners": [
        "Zubair Ahmad Bhat",
        "Mr. Wajid Mohammad Haseeb"
      ],
      "respondents": [
        "Union Territory of Jammu and Kashmir and Anr. (Home Department)"
      ]
    },
    {...},
    {...}
  ],
  "first_id": "JKHC01-003443-2023",
  "last_id": "JKHC01-003543-2023",
  "has_more": true,
}

Retrieve case

Retrieve a case.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

Returns

The case object matching the specified ID.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const courts = await kanoon.courts.cases.retrieve("JKHC01", "JKHC01-003375-2023");

  console.log(courts);
}

main()

Response

{
  "id": "JKHC01-003375-2023",
  "object": "case",
  "court_id": "JKHC01",
  "filed_at": "2023-07-15",
  "registered_at": "2023-07-15",
  "status": "in_progress",
  "type": "HCP",
  "state": "Jammu and Kashmir",
  "district": "Srinagar",
  "petitioners": [
    "Kaisar Ahmad Sheikh",
    "Mr. S.A. Hussain"
  ],
  "decided_at": null,
  "respondents": [
    "Union Territory of Jammu and Kashmir and Ors. (Home Department)"
  ]
}

Case Events

This object represents events that occur in a case.

The case event object

This is an object representing a case event.

string

The unique identifier of the case event.

object

string

The object type, which is always court.case.event.

case_id

string

The ID of the case this event belongs to.

judge

string

The judge presiding over the event.

scheduled_at

string

The date the event is scheduled to occur.

heard_at

string

The date the event was heard.

purpose

string

The purpose of the event, which can either be admission, final_hearing, orders, judgment, dismissal, evidence, procedural, filing, transferred, infructuous, or other.

Read more about case event purposes.

The case event object

{
  "id": "event_abc123",
  "object": "court.case.event",
  "case_id": "JKHC01-003375-2023",
  "judge": "Justice Alok Aradhe",
  "scheduled_at": "2023-07-15",
  "heard_at": "2023-07-20",
  "purpose": "final_hearing"
}

List case events

Returns a list of events for a given case.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/events

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

Query parameters

limit

number

Optional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order

string

Optional

Sort order by the scheduled_at timestamp of the objects. asc for ascending order and desc for descending order.

after

string

Optional

before

string

Optional

filter

string

Optional

Filter by event purpose. Either admission, final_hearing, orders, judgment, dismissal, evidence, procedural, filing, transferred, infructuous, or other.

Read more about case event purposes.

Returns

A list of case event objects.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const events = await kanoon.courts.cases.events.list("JKHC01", "JKHC01-003375-2023", {
    limit: 5,
    order: "desc",
  });

  console.log(events);
}

main()

Response

{
  "object": "list",
  "data": [
    {
      "id": "event_abc123",
      "object": "court.case.event",
      "case_id": "JKHC01-003375-2023",
      "judge": "Justice Alok Aradhe",
      "scheduled_at": "2023-07-15",
      "heard_at": "2023-07-20",
      "purpose": "final_hearing"
    },
    {...},
    {...}
  ],
  "first_id": "event_abc123",
  "last_id": "event_xyz789",
  "has_more": true,
}

Retrieve case event

Retrieve a case event.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/events/{event_id}

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

event_id

string

Required

The ID of the event to use for this request.

Returns

The case event object matching the specified ID.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const event = await kanoon.courts.cases.events.retrieve("JKHC01", "JKHC01-003375-2023", "event_abc123");

  console.log(event);
}

main()

Response

{
  "id": "event_abc123",
  "object": "court.case.event",
  "case_id": "JKHC01-003375-2023",
  "judge": "Justice Alok Aradhe",
  "scheduled_at": "2023-07-15",
  "heard_at": "2023-07-20",
  "purpose": "final_hearing"
}

Case event purposes

Case events can have various purposes that describe the reason for the event. Use these purposes to understand the context of the event and the stage of the case.

admission

The case is being considered for admission, which means the court is deciding whether to accept and proceed with the case. This can be for new (fresh) or existing (non-fresh) cases.

final_hearing

The case is in the final stages of hearing, where all arguments and evidence are presented, and the court is ready to make a final decision or disposal of the case.

orders

The court is issuing specific orders related to the case. This can involve various procedural or substantive directives that the court needs to issue.

judgment

The court is delivering a judgment, which is the final decision on the case. This includes cases where the judgment is reserved for a later date.

dismissal

The case is being dismissed, meaning it is being closed without a full hearing or trial, often because it is found to be without merit, withdrawn, or otherwise resolved.

evidence

The case is at a stage where evidence is being presented or considered, or further proceedings related to evidence are taking place.

procedural

The case involves procedural steps such as framing issues to be decided, adding or removing parties (impleadment), ensuring proper service of documents, or taking other necessary steps to advance the case.

filing

The case requires the filing of certain documents, such as objections, replies, responses, or counter affidavits. These filings are part of the case's progress through the court system.

transferred

The case is being transferred to another tribunal or court, such as the Central Administrative Tribunal, often due to jurisdictional reasons.

infructuous

The case is deemed infructuous, meaning it has become moot or irrelevant, often because the issues have already been resolved or no longer require a court decision.

other

Any other purposes not covered by the above categories. This is a catch-all for miscellaneous or less common purposes.

Insights

This object represents an insight of a case.

The insight object

This is an object representing a insight.

string

The unique identifier of the insight.

object

string

The object type, which is always insight.

type

string

The type of the insight.

data

string

Additional data about the insight.

The insight object

{
  "id": "insight_abc123",
  "object": "insight",
  "type":"outcome",
  "data":{
    "outcome":{
      "type":"infructuous",
      "reason":"The petition was disposed of because the detenu has been released, resulting in the petition becoming no longer valid."
    }  
  }
}

List insights

Returns a list of insights for a given case.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/insights

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

Returns

A list of insight objects.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const insights = await kanoon.courts.cases.insights.list("JKHC01", "JKHC01-003375-2023");

  console.log(insights);
}

main()

Response

{
  "object": "list",
  "data": [
    {
      "id": "insight_abc123",
      "object": "insight",
      "type":"outcome",
      "data":{
        "outcome":{
          "type":"infructuous",
          "reason":"The petition was disposed of because the detenu has been released, resulting in the petition becoming no longer valid."
        }  
      }
    },
    {...},
    {...}
  ],
  "first_id": "insight_abc123",
  "last_id": "insight_xyz789",
  "has_more": true,
}

Retrieve insight

Retrieve a insight object.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/insights/{insight_id}

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

insight_id

string

Required

The ID of the insight to use for this request.

Returns

The insight object matching the specified ID.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const insight = await kanoon.courts.cases.insights.retrieve("JKHC01", "JKHC01-003375-2023", "insight_abc123");

  console.log(insight);
}

main()

Response

{
  "id": "insight_abc123",
  "object": "insight",
  "type":"outcome",
  "data":{
    "outcome":{
      "type":"infructuous",
      "reason":"The petition was disposed of because the detenu has been released, resulting in the petition becoming no longer valid."
    }  
  }
}

Orders

This object represents an order of a case.

The order object

This is an object representing a order.

string

The unique identifier of the order.

object

string

The object type, which is always court.case.order.

created_at

string

The date the order was created.

judges

string[]

The list of judges involved in issuing the order.

url

string

A URL pointing to the order pdf.

notes

string[]

A list of order snippets

The order object

{
  "id": "JKHC01-0000001-2020-1",
  "object": "court.case.order",
  "created_at": "2024-01-01",
  "judges": ["Justice Alok Aradhe"],
  "url": "https://file.kanoon.dev/orders/HCBM01-000000123-2015?Expires=1716502780&Signature=lZljjzI3V7iqv0lgvuX8rGJ8%2FyQlF1LCMf9scnWuJhY6t8DyoJxW93GfSYoDZXZJXNiv0Zq3zX2C7blhHQBNBw%3D%3D&Key-Pair-Id=APKAX1YF3XAMPLE99J3GQ",
  "notes": [
    "In the case before the High Court of Judicature at Bombay, the court heard the counsels for the petitioner and the state, along with Shweta Singh, her parents, and the investigating officer.",
    "The NGO's report indicated that Shweta showed confusion and uncertainty about her future during counseling sessions. They recommended that both Shweta and her parents undergo additional counseling to enhance their relationships and create a healthier environment.",
    "Considering the situation, the court decided to adjourn the matter to November 18, 2015, at 3:00 p.m., and instructed that the counseling sessions with the NGO continue. Shweta is to remain in her parents' custody, and police officers are to ensure she comes to court on the next date."
  ]
}

List orders

Returns a list of court case orders for a given case.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/orders

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

Returns

object

string

The object type, which is always list.

data

order[]

A list of order objects.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const orders = await kanoon.courts.cases.orders.list("JKHC01", "JKHC01-003375-2023");

  console.log(orders);
}

main();

Response

{
  "object": "list",
  "data": [
    {
      "id": "JKHC01-0000001-2020-1",
      "object": "court.case.order",
      "created_at": "2024-01-01",
      "judges": ["Justice Alok Aradhe"],
      "url": "https://file.kanoon.dev/orders/HCBM01-000000123-2015?Expires=1716502780&Signature=lZljjzI3V7iqv0lgvuX8rGJ8%2FyQlF1LCMf9scnWuJhY6t8DyoJxW93GfSYoDZXZJXNiv0Zq3zX2C7blhHQBNBw%3D%3D&Key-Pair-Id=APKAX1YF3XAMPLE99J3GQ",
      "notes": [
        "In the case before the High Court of Judicature at Bombay, the court heard the counsels for the petitioner and the state, along with Shweta Singh, her parents, and the investigating officer.",
        "The NGO's report indicated that Shweta showed confusion and uncertainty about her future during counseling sessions. They recommended that both Shweta and her parents undergo additional counseling to enhance their relationships and create a healthier environment.",
        "Considering the situation, the court decided to adjourn the matter to November 18, 2015, at 3:00 p.m., and instructed that the counseling sessions with the NGO continue. Shweta is to remain in her parents' custody, and police officers are to ensure she comes to court on the next date."
      ]
    },
    {...},
    {...}
  ],
  "first_id": "JKHC01-0000001-2020-1",
  "last_id": "JKHC01-0000001-2020-3",
  "has_more": true,
}

Retrieve order

Retrieve an order.

GET
https://api.kanoon.dev/v1/courts/{court_id}/cases/{case_id}/orders/{order_id}

Path parameters

court_id

string

Required

The ID of the court to use for this request.

case_id

string

Required

The ID of the case to use for this request.

order_id

string

Required

The ID of the order to retrieve.

Returns

The order object matching the specified ID.

Example Request

import { Kanoon } from "kanoon";

const kanoon = new Kanoon({
  apiKey: "sk-xxxx",
});

async function main() {
  const order = await kanoon.courts.cases.orders.retrieve("JKHC01", "JKHC01-003375-2023", "JKHC01-0000001-2020-1");

  console.log(order);
}

main();

Response

{
  "id": "JKHC01-0000001-2020-1",
  "object": "court.case.order",
  "created_at": "2024-01-01",
  "judges": ["Justice Alok Aradhe"],
  "url": "https://file.kanoon.dev/orders/HCBM01-000000123-2015?Expires=1716502780&Signature=lZljjzI3V7iqv0lgvuX8rGJ8%2FyQlF1LCMf9scnWuJhY6t8DyoJxW93GfSYoDZXZJXNiv0Zq3zX2C7blhHQBNBw%3D%3D&Key-Pair-Id=APKAX1YF3XAMPLE99J3GQ",
  "notes": [
    "In the case before the High Court of Judicature at Bombay, the court heard the counsels for the petitioner and the state, along with Shweta Singh, her parents, and the investigating officer.",
    "The NGO's report indicated that Shweta showed confusion and uncertainty about her future during counseling sessions. They recommended that both Shweta and her parents undergo additional counseling to enhance their relationships and create a healthier environment.",
    "Considering the situation, the court decided to adjourn the matter to November 18, 2015, at 3:00 p.m., and instructed that the counseling sessions with the NGO continue. Shweta is to remain in her parents' custody, and police officers are to ensure she comes to court on the next date."
  ]
}