Foreman API documentation

August 21, 2025 · View on GitHub

Generated HTML API documentation for the Foreman and its plugins via apipie-rails.

The content is hosted at https://apidocs.theforeman.org

For Foreman documentation go to https://docs.theforeman.org

Adding new version

Follow these steps to add a new version:

Foreman

Fetch API docs for Foreman:

  1. Go to https://github.com/theforeman/foreman/actions/workflows/foreman.yml?query=branch%3AX.Y-stable
  2. Pick the latest run of the action
  3. Download the apidoc-* artifact (there might be multiple, pick any one of them)

You can also do this from the CLI using gh:

gh run download --repo theforeman/foreman --pattern 'apidoc-*' $(gh run list --repo theforeman/foreman --workflow foreman.yml --branch X.Y-stable --status completed --limit 1 --json databaseId --jq '.[].databaseId')

Note: gh will automatically unzip the artifacts, so you only have to copy them.

Prepare folder for the new version (X.Y)

  1. cd foreman
  2. cp -r TEMPLATE X.Y
  3. ln -snf X.Y latest
  4. unzip -d X.Y/apidoc ~/Downloads/apidoc-<…>.zip
  5. run cleanup script in the root of the apidocs repo: cleanup.sh
  6. update index.html file with a link to the new page

Katello

Generate API docs in a Foreman + Katello development environment:

  1. cd to the katello directory and checkout the relevant release branch
  2. cd to the foreman directory and checkout the relevant stable branch
  3. APIPIE_RECORD=examples bundle exec rake test
  4. RAILS_ENV=production FOREMAN_APIPIE_LANGS=en bundle exec rake apipie:cache

Prepare folder for the new version (X.Y)

  1. cd to the apidocs/katello directory
  2. cp -r TEMPLATE X.Y
  3. ln -snf X.Y latest
  4. cp -r dir/to/foreman/public/apipie-cache/apidoc/* X.Y/apidoc
  5. run cleanup script in apidocs repo: cleanup.sh
  6. update index.html file with a link to the new page

LICENSE

All files are auto-generated and distributed under GNU GPL v3 conditions. See the LICENSE file for more info.