Aide silicon ioi

This documentation explains how to query the ioi REST API to retrieve raw data from the database: listing records of a doctype, or reading one in detail.

It covers reading data only. It is based on the native REST API of the Frappe framework, on which ioi is built.

In the examples below, replace <base-url> with the URL of your ioi instance.

Authentication #

API access uses an API Key and an API Secret, generated from your user settings.

These two values are concatenated with a : and sent in the Authorization HTTP header, in the following format:

Authorization: token api_key:api_secret

Example - cURL #

curl http://<base-url>/api/method/frappe.auth.get_logged_user \
  -H "Authorization: token api_key:api_secret"

Example - JavaScript (fetch) #

fetch('http://<base-url>/api/method/frappe.auth.get_logged_user', {
    headers: {
        'Authorization': 'token api_key:api_secret'
    }
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

Every call described below must include this Authorization header.

Listing Documents #

Retrieves a list of records for a given doctype.

GET /api/resource/:doctype

By default, the response contains 20 records and only shows the name field.

Example response:

{
  "data": [
    {"name": "f765eef382"},
    {"name": "2a26fa1c64"},
    {"name": "f32c68060f"}
  ]
}

Choosing the fields to return #

GET /api/resource/:doctype?fields=["field1", "field2"]

Example response:

{
  "data": [
    {"description": "Business worker talk society...", "name": "f765eef382"},
    {"description": "This reveal as look near sister...", "name": "2a26fa1c64"}
  ]
}

Expanding a linked field (expand) #

Returns the full details of a linked field instead of just its identifier.

GET /api/resource/:doctype?expand=["priority"]

Example response: the priority field returns the full object instead of just its identifier:

{
  "data": [
    {
      "name": "f765eef382",
      "priority": {
        "name": "a1b2c3",
        "title": "Medium",
        "creation": "2025-11-05 19:02:19.106966"
      }
    },
    {
      "name": "f765eef393",
      "priority": {
        "name": "a1b2c4",
        "title": "High",
        "creation": "2025-11-05 20:02:19.106966"
      }
    }
  ]
}

Filtering results #

The filters parameter takes an array of conditions in the format ["field", "operator", "value"], combined with AND logic:

GET /api/resource/:doctype?filters=[["field1", "=", "value1"], ["field2", ">", "value2"]]

To combine conditions with OR logic, use or_filters with the same syntax.

Sorting results #

GET /api/resource/:doctype?order_by=title%20desc

Pagination #

GET /api/resource/:doctype?limit_start=5&limit_page_length=10

Example response:

{
  "data": [
    {"name": "6234d15099"},
    {"name": "62f2181ee0"},
    {"name": "a50afbbfaa"},
    {"name": "aa12a5cf71"},
    {"name": "6ac9800d4e"},
    {"name": "4bcf8b701c"},
    {"name": "aee15f4c20"},
    {"name": "6ba753afef"}
  ]
}

An alternative syntax exists using limit:

GET /api/resource/:doctype?limit_start=5&limit=10

List-style response format #

By default, each record is returned as a dictionary (key/value pairs). To get a list of values instead of a dictionary:

GET /api/resource/:doctype?limit_start=5&limit=5&as_dict=False

Example response: each record becomes a list of values (here, a single field is returned) instead of a dictionary:

{
  "data": [
    ["6234d15099"],
    ["62f2181ee0"],
    ["a50afbbfaa"]
  ]
}

Debug #

To display the executed SQL query along with its execution time:

GET /api/resource/:doctype?limit_start=10&limit=5&debug=True

Example response: the executed SQL query appears in the exc field, alongside the data:

{
  "data": [
    {"name": "4bcf8b701c"},
    {"name": "aee15f4c20"},
    {"name": "6ba753afef"},
    {"name": "f4b7e24abc"},
    {"name": "bd9156096c"}
  ],
  "exc": "[\"select `tabToDo`.`name`\\n\\t\\t\\tfrom `tabToDo`\\n\\t\\t\\t\\n\\t\\t\\t\\n\\t\\t\\t order by `tabToDo`.`modified` DESC\\n\\t\\t\\tlimit 5 offset 10\", \"Execution time: 0.0 sec\"]"
}

Reading a Specific Document #

Retrieves the full detail of a record, based on its identifier (name).

GET /api/resource/:doctype/:name

Example response:

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "<p>Test description</p>",
    "doctype": "ToDo"
  }
}

Expanding linked fields #

So that link fields return the full object instead of just their identifier:

GET /api/resource/:doctype/:name?expand_links=True

Example response: here, priority returns the full object instead of just its identifier:

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": {
      "name": "a1b2c3",
      "title": "Medium",
      "creation": "2025-11-05 19:02:19.106966"
    },
    "description": "<p>Test description</p>",
    "doctype": "ToDo"
  }
}

Summary #

This API exclusively allows you to read data already present in the database: lists of records and individual documents.

Aussi pour cet écran

Documentation (EN)