i-doit enables external access to the IT documentation via an application programming interface (API). With the API data can be read, created, updated and deleted. Thus the API offers similar functions like the Web GUI but the additional benefit is that you can automate them without any problems.
The API of i-doit provides typical CRUD functionalities. With this, files can be
- Updated and
API queries can take place in an asynchronous way without losing the relation between requests and responses. The utilized programming language can be chosen freely.
API instead of database
It's strongly recommended to prefer the API to database manipulations at all times. SQL statements bypass all sorts of internal processes. If a data record is manipulated via SQL per
INSERT, UPDATE or
DELETE, this could risk data integrity and could even disable i-doit.
The API is configured via the Web GUI of i-doit and can be found at
Administration → Interfaces / external data → JSON-RPC API.
Removing HTML tags from description fields is only possible at i-doit version 1.15.2 with API version 1.11.3 installed.
Please note that the logging of API requests will create a file in the install path of i-doit at
log/ for each request. This may lead to increased requirements of memory space in case the API is used intensively.
You can access the API of i-doit by activating a special URL. Add
src/jsonrpc.php to the basic URL:
Authentication and Authorization
You need an API key so that requests will be processed by the API. Additionally, you can activate the function that a dedicated user account is activated for log-in. Permissions for this account can be set as usual. Otherwise all permissions are available through the API. Another advantage is the fact that a dedicated user can be set per third-party system/ script; this makes it easier to keep track of the data flow.
It may prove useful to use the API method
idoit.login for a single authentication if a lot of requests (meaning thousands) are sent from a client. Otherwise it is possible that too many sessions are created in a very small time frame but are not terminated. This could result in the fact that i-doit stops working until the sessions have been terminated.
Please see this article for detailled information about each method.
|Display installed i-doit add-ons|
|Display licensed objects and add-ons|
|Search in i-doit|
|Display the version of i-doit|
|Create a category entry|
|Update a category entry|
|Delete a category entry|
|Quickpurge a category entry|
|Purge a category entry|
|Recycle a category entry|
|Archive a category entry|
|Create/Update a category entry|
|Create a category entry (deprecated)|
|Read the attributes of a category|
|Read the values of a dialogue field|
|Create the values of a dialogue field|
|Update the values of a dialogue field|
|Delete the values of a dialogue field|
|Recursive query of all object relations|
|Read logbook entry|
|Create logbook entry|
|Read an object|
|Create an object|
|Update an object|
|Quickpurge an object|
|Recycle an object|
|Archive an object|
|Delete an object|
|Purge an object|
|Read which object types are assigned to which object type groups|
|Read which categories are configured to which object types|
|Query object types|
|Read objects by relation type|
With a simple example we create a new object of the type
Server with the object title "My little server" via the API.
Request to server:
Via cURL you can send this request for test purposes:
Categories in the IT Documentation
A helpful listing of all categories and attributes used in i-doit is provided by a special URL:
For example, this listing shows you which name is used to access categories and attributes and which data types are expected by these attributes.
Clients and Libraries
There are numerous projects and products applying the API by i-doit. We would like to introduce some clients and libraries:
i-doit API client
Should a client or a library be missing in this article, we appreciate a short message to email@example.com.
Documentation for Download
You can download a documentation maintained by the developers as PDF file. (out-dated)
|1.12.2||2021-08-09||[Improvement] New parameters "offset" and "limit" for the "cmdb.category.read" method|
[Bug] Virtual Switches > Creating Port Groups generates SQL error message
[Bug] Cluster members cannot be assigned via API using the category C__CATG__CLUSTER_MEMBERSHIPS
[Bug] The API can not create sub-categories in 'cmdb.object.create' context
[Bug] Layer 3 nets cannot be assigned with API validation enabled in Layer 2 nets
[Bug] When the layer 3 net is changed the layer 3 net is assigned to itself under layer 2 net assignment
[Bug] The category SLA (C__CATG__SLA) cannot be described via the API / With API validation switched off the category is emptied
[Bug] Dialog+ fields with 'PropertyFactory' definition can not be written
|1.12.1||2021-01-18||[Bug] cmdb.category.quickpurge cannot be used with custom categories|
[Bug] API version 1.12 can no longer be used in the open variant of i-doit
|1.12||2021-01-14||[Bug] API: It is not possible to create a volume license via the API if "type": "volume license" is used|
[Bug] Saving the "Layer-2 Nets" category deletes ip helper
[Bug] Contact assignment of a group of people will be deleted if it is updated via the API
|1.11.3||2020-12-01||[Bug] Assign cable with fibers/leads while saving connection|
[Bug] Limit assignment categories to one entry while creating
[Bug] Do not connect root location while creating cluster membership
[Bug] Do not create wrong output after removing cable connection
[Bug] Cannot assign objects to category "locally assigned objects" (requires i-doit 1.15.1)
[Bug] The category C__CATG__IMAGE is not read correctly via the API
[Bug] The category C__CATG__IMAGE cannot be written correctly
[Bug] The dates of the category contract information cannot be set via the API
[Bug] Category > Assigned Subscriptions C__CATG__ASSIGNED_SUBSCRIPTIONS key uuid cannot be set via string only via int
[Bug] Read Methods: Do not output HTML tags in description fields
[Bug] Objects can only be created via the API if the right to all object types is granted
[Bug] Ports cannot be uniquely referenced via the API
[Bug] Empty string supplied via API
|1.11.2||2020-06-24||[Bug] API method: cmdb.object overrides the rights system|
[Bug] Updates via the API (save method) sets arbitrary entries in the Virtual Host category
[Bug] Do not connect root location while creating cluster membership
[Improvement] Add RPC to handle the CMDB status
[Bug] Assignment of devices to segments in slots not possible
[Bug] cmdb.category.read: Read entries by state "normal" unless otherwise noted
[Bug] Authentication with LDAP not possible
[Improvement] Enable validation of API requests via expert setting
[Bug] cmdb.reports.read throws SQL error for variable reports
[Bug] Method cmdb.reports throws PHP warning
[Bug] After creating an object, a reindex is substantial to find an object via the search
[Bug] Unable to create entries in category C__CATS__ORGANIZATION_CONTACT_ASSIGNMENT
[Bug] API ignores language parameter
[Improvement] Searching for objects by attributes and values
[Improvement] Enforce user rights for API calls
[Improvement] Create object via "cmdb.object.create" with optional template
[Bug] Unable to upload file
[Bug] Logbook title is empty when saving a custom category
[Bug] User-defined dialog plus contents select via API
[Bug] Unable to read passwords
[Bug] Method 'cmdb.object.create' creates object id's partly as string, partly as integer
[Bug] Database error when trying to delete an object, which does not exist anymore, via the API
[Bug] Dialog Plus fields that have a dependency on another attribute have not been created.
[Bug] Self-defined Dialog+ fields won't be displayed after creating them
[Bug] Created dialog entries receive status 1 instead of 2 (normal)
[Bug] cmdb.object.delete ignores parameter "status"
[Bug] cmdb.category.create throws database error for category "model"
Since version 1.8.1 the API is released as an add-on. Pre-releases were bundled with i-doit.