Documentation
API

API

Web configuration

The HTTP api endpoint is /api/.

Example:

curl -v http://localhost/api/ping/
curl -v http://localhost:8000/api/ping/
curl -v https://mycavaliba.host.com/api/ping/

You may need to update your current nginx.conf if coming from an older Cavaliba release (3.26 and earlier). Add the proper location as described here. You may download a newer release to see a complete configuration.

The key point is to make the /api/ endpoint available without OAUTH2 or other Basic Authentication scheme. API Authentication is based on headers and shared secrets.

nginx.conf entry for /api/

# -----------------------
# nginx - cavaliba api
# -----------------------

location /api/ {

    # no SAM/OIDC/OAUTH2 authentication
    # no middleware authentication (Basic Auth / Digest)

    # for API / file upload:
    client_max_body_size 20M;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    real_ip_header X-Real-IP;
    #proxy_set_header X-Real-IP $remote_addr;
    proxy_redirect off;
    proxy_http_version 1.1;

    proxy_pass http://cavaliba_app;

    }

Authentication

Most API calls must provide a valid API Key. API Keys are created in the User Interface (sidebar / API Key), with a short keyname, a secret and Authorizations.

Example:

curl -H "X-Cavaliba-Key: test mysecret" https://my-secure-cavaliba.com/api/version/

Warning: always use HTTPS to avoid API key clear-text eavesdropping.

Authorizations

Most API calls must have valid authorizations, for the requested operation. Authorizations are configured in the ACL Authorization Text Field of each API Key.

You provide a list of permissions which are concatenated. You can use a ! to remove (negate) a set of permissions.

Example:

## ACL Authorisations

p_info
p_data_site_read
p_data_app_read
!p_data_app_read
role:role_test01

Import/Export API Keys

You can import/export API Key with a yaml snippet:

- classname: _apikey
    keyname: test
    displayname: test
    is_enabled: true
    secret: "$sha256$3146ac549c20d3dd58c353483f8ea493$bab660e7a4996ec851cfe32f02b47b3b3f5a8b658ce1589222f2ce1655abaad9$"
    description: Test API Key
    ip_filter: '*'
    acl: "role:role_admin"

At the moment, secrets must be set from the UI editor.

Special authorizations

  • special authorization : timerange, IP range

Endpoints

  • /api/ping/
  • /api/version/
  • /api/info/
  • /api/users/
  • /api/schemas/
  • /api/assets/

Common options 

o=[json|yaml|txt]            output format
id=<INT>                     object id for requested action
schema=SCHEMA_NAME           schema name   
page=<int>                   page
size=<int>                   number of items
search=SEARCH_PATTERN        search string 
refs=[_user,_group,_role[*|schema1,schema2,...]]          
                             add details for inline object (references)
rev=<int>                    add revision history to exported object

option: revisions

New: V3.30

Include the last N revisions of each asset in a _revision field. Each entry contains the login, date, and action.

curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/site/GAVLE/?rev=2
{
  "id": 42,
  "classname": "site",
  "keyname": "GAVLE",
  (...)
  "_revision": [
    {"login": "admin", "date": "2026-03-14T10:22:01", "action": "edit"},
    {"login": "alice",  "date": "2026-03-10T08:15:44", "action": "edit"}
  ]
}

If rev=0 or absent, no _revision field is returned.

option: references

New: V3.30

References add details for the inline objects in a _refs field of each exported object.

curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/968/?refs=*,_user
{
  "id": 968,
  "classname": "test",
  (...)
  "my_user": "adela81",
  "_refs": {
    "_user": [
      {
        "login": "adela81",
        "displayname": "Marijn Torrecilla",
        "firstname": "Marijn",
        "lastname": "Torrecilla",
        "email": "Torrecilla@demo.cavaliba",
        "mobile": "+56-16832089",
        "external_id": "BA-948192"
      }
    ],

    "test": [
      {
        "keyname": "test02",
        "classname": "test",
        "displayname": "test02"
      }
    ],
    "site": [
      {
        "keyname": "GAVLE",
        "classname": "site",
        "displayname": "Gavle Rehabilitation Center"
      }
    ]
  }
}

ping

Returns a simple JSON response to check connectivity to the cavaliba API.

  • Authentication required: no
curl http://localhost:8000/api/ping/
{
  "status": "OK"
}

server version

Returns the remote Cavaliba version.

  • Authentication required: yes
  • Permission required: p_info
curl -H "X-Cavaliba-Key: test a_secret_key" http://localhost:8000/api/version/
{
  "version": "3.29.0"
}

info

Returns statistics about the Cavaliba instance.

  • Authentication required: yes
  • Permission required: p_info
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/info/
{
  "schema_count": 26,
  "field_count": 251,
  "instance_count": 970,
  "instance_eav": 8843,
  "instance_file": 2,
  "user_count": 512,
  "group_count": 65,
  "role_count": 16,
  "permission_count": 141,
  "visitor_count": 0,
  "configuration_count": 56,
  "log_count": 4989,
  "apistat_count": 1,
  "dashboard_count": 24,
  "smsjournal_count": 0,
  "status_raw_count": 1820,
  "status_sample_hour_count": 168,
  "status_sample_day_count": 22
}

users

Returns a list of users. Supports filtering by id, keyname, or search pattern.

  • Authentication required: yes
  • Permission required: p_user_read

Reference:

curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/users/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/users/<id>/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/users/<key>/
curl -H "X-Cavaliba-Key: test mysecret" "http://localhost:8000/api/users/?search=alice&page=1&size=10"

Example:

curl -H "X-Cavaliba-Key: test mysecret" 'http://localhost:8000/api/users/adela81/'
{
  "classname": "_user",
  "login": "adela81",
  "external_id": "BA-948192",
  "email": "Torrecilla@demo.cavaliba",
  "mobile": "+56-16832089",
  "firstname": "Marijn",
  "lastname": "Torrecilla",
  "displayname": "Marijn Torrecilla",
  "description": "User Marijn Torrecilla for cavaliba demo",
  "is_enabled": true,
  "want_notifications": true,
  "want_24": false,
  "want_sms": false,
  "want_email": true
}


curl -H "X-Cavaliba-Key: test mysecret" 'http://localhost:8000/api/users/?search=adela8'
(...)


curl -H "X-Cavaliba-Key: test mysecret" 'http://localhost:8000/api/users/?search=ad&size=2&o=yaml'
- classname: _user
  login: adela81
  external_id: BA-948192
  email: Torrecilla@demo.cavaliba
  mobile: +56-16832089
  firstname: Marijn
  lastname: Torrecilla
  displayname: Marijn Torrecilla
  description: User Marijn Torrecilla for cavaliba demo
  is_enabled: true
  want_notifications: true
  want_24: false
  want_sms: false
  want_email: true

- classname: _user
  login: adelaarmeike
  external_id: AC-401294
  email: Warmer@demo.cavaliba
  mobile: +229-70330545
  firstname: Juliane
  lastname: Warmer
  displayname: Juliane Warmer
  description: User Juliane Warmer for cavaliba demo
  is_enabled: true
  want_notifications: false
  want_24: true
  want_sms: true
  want_email: true

schemas

Returns a list of all schemas, or the detail of a single schema by keyname.

  • Authentication required: yes
  • Permission required: p_schema_read
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/schemas/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/schemas/<keyname>/

Example:

curl -H "X-Cavaliba-Key: test mysecret" "http://localhost:8000/api/schemas/site/?o=yaml"
curl -H "X-Cavaliba-Key: test mysecret" "http://localhost:8000/api/schemas/site/"
{
  "classname": "_schema",
  "keyname": "site",
  "displayname": "Sites",
  "is_enabled": true,
  "_options": {
    "icon": "fa-hospital-o",
    "keyname_mode": "edit",
    "keyname_label": "Keyname",
    "displayname_label": "Displayname",
    "p_admin": "p_data_site_admin",
    "p_create": "p_data_site_create",
    "p_read": "p_data_site_read",
    "p_update": "p_data_site_update",
    "p_delete": "p_data_site_delete"
  },
  "country": {
    "displayname": "Country code",
    "description": "Country code",
    "is_enabled": true,
    "dataformat": "string",
    "dataformat_ext": "",
    "order": 104,
    "page": "Postal Address",
    "cardinal_min": 0,
    "cardinal_max": 1,
    "default_value": ""
  },
  "zip": {
    "displayname": "ZipCode",
    "description": "ZipCode",
    "is_enabled": true,
    "dataformat": "string",
    "dataformat_ext": "",
    "order": 106,
    "page": "Postal Address",
    "cardinal_min": 0,
    "cardinal_max": 1,
    "default_value": ""
  },

(...)

assets

Returns instances (assets). Supports filtering by id, schema+keyname, or search pattern. Read permission is checked per instance and schema.

  • Authentication required: yes
  • Permission required: per schema (e.g. p_data_<schema>_read)
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/<id>/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/<schema>/<keyname>/
curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/assets/?search=zzz
curl -H "X-Cavaliba-Key: test mysecret" "http://localhost:8000/api/assets/?search=zzz&refs=*&expand=true"

imports

Import data via POST. Supports JSON, YAML, and CSV content types. Optional pipeline and schema parameters.

  • Authentication required: yes
  • Permission required: p_data_import and per object permission
curl -X POST -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/import/ \
    -H 'Content-Type: application/json' --data-binary \
    @mydir/myfile.json
 
curl -X POST -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/import/ \
    -H 'Content-Type: text/x-yaml' --data-binary \
    @myfile.yaml


curl -X POST -H "X-Cavaliba-Key: test mysecret" \
     "http://localhost:8000/api/import/?pipeline=test_api" \
     -H 'Content-Type: text/x-yaml' --data-binary \
     @myfile.yaml 


curl -X POST -H "X-Cavaliba-Key: test mysecret" \
     "http://localhost:8000/api/import/?pipeline=test_api&schema=_user&delimiter=," \
     -H 'Content-Type: text/csv' --data-binary \
     @myfile.csv

App STATUS worklist 

curl -H "X-Cavaliba-Key: test mysecret" http://localhost:8000/api/appstatus/worklist/ | jq .
{
  "version": "1234567890",
  "monitors": [
    {
      "keyname": "apache",
      "displayname": "www.apache.org",
      "type": "HTTP",
      "is_enabled": true,
      "timeout": 2000,
      "target": "https://www.apache.org/",
      "http_code": 200,
      "http_ssl_verify": true,
      "http_allow_redirect": true,
      "http_pattern": "Foundation"
    }
  ]
}