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.

id
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.

id
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
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.
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.

id
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.
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",
}

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
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 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"
    },
    {...},
    {...}
  ],
  "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",
}

Insights

This object represents an insight of a case.

The insight object

This is an object representing a insight.

id
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_c402ea7178e74613afbcd142fc39a7cb",
  "object": "insight",
  "type": "party_composition",
  "data": {
    "party_composition": {
      "reasoning": "The petitioner is represented by Rajkumar Chandrakant Mhatre and Udaynath Tripathi, both classified as individuals acting in their personal capacities. The respondent is a government entity, specifically the Commissioner of Police, Navi Mumbai, which is a government official acting within their official capacity. There are no multiple types in either side, hence is_mixed is false for both.",
      "petitioner": "individual",
      "respondent": "government",
      "composition": {
        "petitioner": {
          "parties": [
            {
              "name": "RAJKUMAR CHANDRAKANT MHATRE",
              "type": "individual"
            },
            {
              "name": "Udaynath Tripathi",
              "type": "individual"
            }
          ],
          "primary": "individual",
          "is_mixed": false
        },
        "respondent": {
          "parties": [
            {
              "name": "THE COMMISSIONER OF POLICE NAVI MUMBAI",
              "type": "government"
            }
          ],
          "primary": "government",
          "is_mixed": false
        }
      }
    }
  }
}

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_c402ea7178e74613afbcd142fc39a7cb",
      "object": "insight",
      "type": "party_composition",
      "data": {
        "party_composition": {
          "reasoning": "The petitioner is represented by Rajkumar Chandrakant Mhatre and Udaynath Tripathi, both classified as individuals acting in their personal capacities. The respondent is a government entity, specifically the Commissioner of Police, Navi Mumbai, which is a government official acting within their official capacity. There are no multiple types in either side, hence is_mixed is false for both.",
          "petitioner": "individual",
          "respondent": "government",
          "composition": {
            "petitioner": {
              "parties": [
                {"name": "RAJKUMAR CHANDRAKANT MHATRE", "type": "individual"},
                {"name": "Udaynath Tripathi", "type": "individual"}
              ],
              "primary": "individual",
              "is_mixed": false
            },
            "respondent": {
              "parties": [
                {
                  "name": "THE COMMISSIONER OF POLICE NAVI MUMBAI",
                  "type": "government"
                }
              ],
              "primary": "government",
              "is_mixed": false
            }
          }
        }
      }
    },
    {
      "id": "insight_8e645b60b57be0c3087e3a524b11307b",
      "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_8e645b60b57be0c3087e3a524b11307b",
  "last_id": "insight_c402ea7178e74613afbcd142fc39a7cb",
  "has_more": false
}

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_c402ea7178e74613afbcd142fc39a7cb",
  "object": "insight",
  "type": "party_composition",
  "data": {
    "party_composition": {
      "reasoning": "The petitioner is represented by Rajkumar Chandrakant Mhatre and Udaynath Tripathi, both classified as individuals acting in their personal capacities. The respondent is a government entity, specifically the Commissioner of Police, Navi Mumbai, which is a government official acting within their official capacity. There are no multiple types in either side, hence is_mixed is false for both.",
      "petitioner": "individual",
      "respondent": "government",
      "composition": {
        "petitioner": {
          "parties": [
            {"name": "RAJKUMAR CHANDRAKANT MHATRE", "type": "individual"},
            {"name": "Udaynath Tripathi", "type": "individual"}
          ],
          "primary": "individual",
          "is_mixed": false
        },
        "respondent": {
          "parties": [
            {
              "name": "THE COMMISSIONER OF POLICE NAVI MUMBAI",
              "type": "government"
            }
          ],
          "primary": "government",
          "is_mixed": false
        }
      }
    }
  }
}

Insight Types

Schemas for each available insight type.

The outcome insight object

This is an object representing the outcome of a case.

id
string
The unique identifier of the insight.
object
string
The object type, which is always insight.
type
string
The insight type, which is always outcome.
data
object
Outcome details for the case.
The outcome insight object
{
  "id": "insight_outcome_123",
  "object": "insight",
  "type": "outcome",
  "data": {
    "outcome": {
      "type": "infructuous",
      "reason": "The petition was disposed of because the detenu has been released."
    }
  }
}

The cause insight object

This is an object representing the cause of a case outcome.

id
string
The unique identifier of the insight.
object
string
The object type, which is always insight.
type
string
The insight type, which is always cause.
data
object
Reason for the case outcome.
The cause insight object
{
  "id": "insight_cause_123",
  "object": "insight",
  "type": "cause",
  "data": {
    "cause": {
      "reason": "Filing delay resulted in dismissal."
    }
  }
}

The party composition insight object

This is an object representing the parties involved in the case.

id
string
The unique identifier of the insight.
object
string
The object type, which is always insight.
type
string
The insight type, which is always party_composition.
data
object
Details about petitioners and respondents.
The party composition insight object
{
  "id": "insight_party_123",
  "object": "insight",
  "type": "party_composition",
  "data": {
    "party_composition": {
      "reasoning": "The petitioner is an individual and the respondent is a government body.",
      "petitioner": "individual",
      "respondent": "government",
      "composition": {
        "petitioner": {
          "parties": [
            { "name": "RAJKUMAR CHANDRAKANT MHATRE", "type": "individual" }
          ],
          "primary": "individual",
          "is_mixed": false
        },
        "respondent": {
          "parties": [
            {
              "name": "THE COMMISSIONER OF POLICE NAVI MUMBAI",
              "type": "government"
            }
          ],
          "primary": "government",
          "is_mixed": false
        }
      }
    }
  }
}

The habeas nature insight object

This is an object describing the nature of a habeas corpus claim.

id
string
The unique identifier of the insight.
object
string
The object type, which is always insight.
type
string
The insight type, which is always habeas_nature.
data
object
Information on the habeas corpus claim.
The habeas nature insight object
{
  "id": "insight_habeas_123",
  "object": "insight",
  "type": "habeas_nature",
  "data": {
    "habeas_nature": {
      "liberty_claim_type": "state_detention",
      "restraint_type": "state",
      "alleged_by": "family",
      "actual_status": "detained",
      "detention_period": {
        "start": "2024-01-01",
        "end": "2024-01-05"
      },
      "reason": "The petitioner claims the detainee is unlawfully held by police."
    }
  }
}

Orders

This object represents an order of a case.

The order object

This is an object representing a order.

id
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."
  ]
}

Search across cases.

Search cases

Search cases using a query string.

GET
https://api.kanoon.dev/v1/search/cases

Query parameters

query
string
Required
Search query string. Use <insight_type>.<field>:<value> to filter by insights.
text
string
Optional
Full-text search across petitioners, respondents, snippets, and transcriptions.
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
A cursor for use in pagination. after is an object ID that defines your place in the list.
before
string
Optional
A cursor for use in pagination. before is an object ID that defines your place in the list.

Returns

A list of case objects that match your query.
Example Request
import { Kanoon } from "kanoon";

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

async function main() {
  const cases = await kanoon.search.cases("court_id:"MHHC01"", {
    text: "example",
  });

  console.log(cases);
}

main();
Response
{
  "object": "list",
  "data": [
    {
      "id": "MHHC01-003443-2020",
      "object": "case",
      "court_id": "MHHC01"
    },
    {...}
  ],
  "first_id": "MHHC01-003443-2020",
  "last_id": "MHHC01-003444-2020",
  "has_more": true
}