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.

Acts

This object represents an act.

The act object

This is an object representing an act.

GET
https://api.kanoon.dev/v1/acts/{act_id}

string

The unique identifier of the act.

object

string

The object type, which is always act.

name

string

The name of the act.

enacted_at

string

The date the act was enacted.

Example Request

import { Kanoon } from "kanoon";

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

async function main() {
  const act = await kanoon.acts.retrieve("COI");

  console.log(act);
}

main()

Response

{
  "id": "COI-1949",
  "object": "act",
  "name": "Constitution of India",
  "enacted_at": "1949-11-26"
}