CircleCI’s REST API documentation is incomplete and erroneous.
The REST API itself is incomplete and buggy.
The least effort solution is conformance to a standard API specification. There are numerous REST API specification standards. One with a lot of attractions is Swagger.
Were CIrcleCI to standardize on Swagger, and generate it’s API using Swagger Codegen the maintenance effort for the API would be greatly reduced and the maintenance effort for the API documentation would reduce to zero.
The API documentation would look like this (but can be completely customized with CSS).
The API specification would look like this.