ARI api-docs returns 500 "Cannot find rest-api directory" on VitalPBX (Asterisk 20) – Fix with symlink

Reporting an Issue VitalPBX 4
1

Problem

When accessing the ARI Swagger documentation endpoint:


http://<PBX_IP>:8088/ari/api-docs/resources.json

the server returns HTTP 500 with the message:

{
  "message": "Cannot find rest-api directory"
}

Even though:

  • ARI is enabled
  • HTTP server is running
  • /usr/share/asterisk/rest-api/*.json exists
  • File permissions are correct

The Asterisk log shows:

res_ari.c: Error determining real directory for rest-api

Root Cause

On VitalPBX, the internal Asterisk setting AST_DATA_DIR points to:

/var/lib/asterisk

The ARI documentation handler always looks for the Swagger JSON files in:

${AST_DATA_DIR}/rest-api

However, the rest-api JSON files are installed by the package in:

/usr/share/asterisk/rest-api

Because of this mismatch, ARI fails to resolve the directory at runtime, even though the files exist and have correct permissions.

This affects only the Swagger / api-docs endpoint.
The ARI REST API itself (/ari/channels, /ari/events, etc.) works normally.

Solution (Recommended)

Create a symbolic link so that the directory exists where Asterisk expects it:

# ensure it does not already exist
sudo ls -ld /var/lib/asterisk/rest-api

# create symlink
sudo ln -s /usr/share/asterisk/rest-api /var/lib/asterisk/rest-api

# ensure ownership is correct
sudo chown -h asterisk:asterisk /var/lib/asterisk/rest-api

# restart asterisk
sudo systemctl restart asterisk

After this, the following endpoint works correctly:

http://<PBX_IP>:8088/ari/api-docs/resources.json

Why this fix is safe

  • No Asterisk configuration files are modified
  • No paths are changed globally
  • Avoids changing astdatadir in asterisk.conf, which could break other components
  • Fully compatible with VitalPBX package layout

Environment

  • VitalPBX
  • Asterisk 20.15.0
  • Debian-based system

Notes

If you don’t need the Swagger docs, this issue can be ignored, as it does not affect ARI functionality itself.
This fix is only required if you want /ari/api-docs/* to work.

Hope this helps others facing the same issue.