Access and use the OpenAPI specification

Explore, download, or generate a client library from the OpenAPI 3.1.0 specification served by automation orchestrator.

Before you begin

A running automation orchestrator instance is available.
You have network access to the automation orchestrator host.

About this task

The specification version corresponds to the automation orchestrator version that serves it. Verify that the specification version matches the automation orchestrator version you are integrating with to avoid compatibility issues.

Procedure

Open Swagger UI to explore the API interactively.
In a web browser, navigate to the following URL, replacing orchestrator_host with the hostname or IP address of your automation orchestrator instance:
```
https://orchestrator_host/api_docs/v1/docs
```
You can also use the shortcut https://orchestrator_host/docs, which redirects to the full path.

Swagger UI displays all available endpoints grouped by domain. You can expand each endpoint to view its parameters, request body schema, and response format.

The APP_ENABLE_TRY_IT_OUT environment variable controls the Try it out option separately and is false by default. An administrator must set APP_ENABLE_TRY_IT_OUT to true to allow running API calls directly from Swagger UI. This variable only takes effect when APP_ENABLE_API_DOCS is also true.
Open ReDoc for a read-friendly API reference.
Navigate to the following URL for a documentation-style rendering of the specification:
```
https://orchestrator_host/api_docs/v1/redoc
```
ReDoc provides a three-panel layout with a navigation sidebar, endpoint details, and request and response examples. This view is optimized for reading and searching the specification.
Download the OpenAPI specification in JSON format.
To download the raw specification, send a GET request:
```
$ curl https://orchestrator_host/api_docs/v1/openapi.json \
  -o openapi.json
```
Save the response to a file for offline reference or client generation.
Optional: Generate a client library from the downloaded specification.
Use an OpenAPI-compatible code generator to produce a typed client library. The following example uses the openapi-generator-cli tool to generate a Python client:
```
openapi-generator-cli generate \
  -i openapi.json \
  -g python \
  -o ./generated-client
```
Replace python with your target language. The generator supports more than 50 languages and frameworks.

Results

Navigate to https://orchestrator_host/api_docs/v1/docs and verify that Swagger UI loads and displays the available API endpoints.
If you downloaded the specification, open the openapi.json file and confirm that it contains the openapi version field and the paths object.