REST API

The server provides a REST API for programmatic access to documentation.

Endpoints

Method	Endpoint	Auth	Description
GET	/api/help	No	Returns human-readable API help
GET	/api/version	No	Returns product name and version
GET	/api/spec	No	Returns OpenAPI 3.0 specification
GET	/api/projects	No	Lists all projects and versions
GET	/api/projects?search=term	No	Filter projects by name
GET	/api/download/{project}/{version}	No	Download project as zip
POST	/api/upload	Yes	Upload documentation (requires auth)
DELETE	/api/delete/{project}/{version}	Yes	Delete a version (requires auth + delete permission)

Authentication

The upload and delete endpoints require token authentication via the X-Token header. Delete additionally requires the token to have allow_delete permission. See Authentication for setup instructions.

Curl Examples

Get Server Version

curl http://example.com/api/version

Response:

{
  "product": "cal-docs-server",
  "version": "DEV"
}

When running from source, the server reports DEV. When installed as a package, it reports the installed package version.

List All Projects

curl http://example.com/api/projects

Response:

{
  "projects": [
    {
      "name": "My Project",
      "directory_name": "my-project",
      "description": "Project description",
      "versions": [
        {
          "version": "1.0.0",
          "directory_name": "my-project-1.0.0",
          "url": "/my-project-1.0.0/",
          "download_url": "/my-project-1.0.0-docs.zip"
        },
        {
          "version": "2.0.0",
          "directory_name": "my-project-2.0.0",
          "url": "/my-project-2.0.0/",
          "download_url": "/my-project-2.0.0-docs.zip"
        }
      ],
      "latest_version_dir": "my-project-2.0.0"
    }
  ],
  "count": 1
}

Search Projects

curl "http://example.com/api/projects?search=my-project"

Download Latest Version

curl -o docs.zip http://example.com/api/download/my-project/latest

Download Specific Version

curl -o docs.zip http://example.com/api/download/my-project/1.2.3

Upload Documentation

curl -X POST -H "X-Token: your-token" \
     -F "file=@my-project-1.0.0-docs.zip" \
     http://example.com/api/upload

The server extracts {project} and {version} from the uploaded filename.

Response:

{
  "success": true,
  "message": "Documentation uploaded successfully",
  "project": "my-project",
  "version": "1.0.0",
  "directory": "my-project-1.0.0",
  "url": "/my-project-1.0.0/",
  "files_extracted": 42
}

Delete a Version

curl -X DELETE -H "X-Token: your-token" \
     http://example.com/api/delete/my-project/1.0.0

Requires a token with allow_delete permission.

Response:

{
  "success": true,
  "message": "Documentation deleted successfully",
  "project": "my-project",
  "version": "1.0.0",
  "directory": "my-project-1.0.0"
}

OpenAPI Specification

The full OpenAPI 3.0 specification is available at /api/spec. You can use this with tools like Swagger UI or to generate client libraries.

curl http://example.com/api/spec

For a quick human-readable overview, see /api/help:

curl http://example.com/api/help