4. Knowledge base API

For filters accessing Knowledgebase items and their properties, see this page.

The knowledge base API supports read-only access to Geneea knowlege base:

  • listing items in a bucket,

  • displaying properties of individual items.

The API requires an X-API-Key.

4.1. Listing items in a bucket

To display only a list of IDs in the abc bucket, you can use the following command:

# list item IDs in 'abc' bucket
curl -v 'https://kb.geneea.com/items?bucket=abc&idsonly=True&limit=5' -H 'X-API-Key: <API-KEY>'

The result is:

{
    "items": ["ABC-1000-VS", "ABC-1001-VS", "ABC-1002-VS", "ABC-1003-VS", "ABC-1004-VS"],
    "paging": {
        "next": "/items?bucket=abc&idsonly=True&pager=eyJwYWdlU2l6ZSI6IDEwLCAib2Zmc2V0R2lkIjogIkNUS0VMRS0xMDA5LVZTIn0%3D"
    }
}

There are a few parameters to this url:

  • bucket=abc - which bucket to access

  • idsonly=[True|False] - to choose whether you want to see full items or only their IDs.

  • limit=5 - specifies the number of items or IDs in the response (up to 100 items which is the default option)

If the list is longer than the specified number of items, you’ll get a string value paging.next for the next list of items. With this you can read the next items with parameter pager=<string> by appending the paging.next value after https://kb.geneea.com as is shown:

# use "paging.next" from the API response for listing another page
curl -v 'https://kb.geneea.com/items?bucket=ctkele&idsonly=False&pager=eyJwYWdlU2l6ZSI6IDEwLCAib2Zmc2V0R2lkIjogIkNUS0VMRS0xMDA5LVZTIn0%3D' -H 'X-API-Key: ... '

4.2. Reading properties of an item

To access a full item with its properties by item ID (ABC-53-VS, ABC-193266, for example) the following command with the right X-API-Key is used.

curl -v 'https://kb.geneea.com/items/ABC-53-VS' -H 'X-API-Key: ... '

You can search the items also with external IDs (as nutscode or localadminunit):

# find 'Liberec region' item by 'nutscode' external ID 'CZ051'
curl -v 'https://kb.geneea.com/search/ids?buckets=abc&externalSource=nutscode&externalIds=CZ051&idsonly=False' -H 'X-API-Key: ... '

The url parameters for this type of command are:

  • bucket=abc - which bucket to access

  • externalSource - name of external source (e.g., localadminunit, nutscode, etc.)

  • externalIds - external ID. It’s a multi-value HTTP GET parameter which can be used multiple times to specify more IDs in one request

  • idsonly=[True|False] - to choose whether you want to see full items or only their IDs.