Home Api OpenAPI Definitions via API

OpenAPI Definitions via API

Use this feature to download a ready-to-use OpenAPI 3 Definition (YAML) for exactly the Workflows that your API Key is assigned to call.

This definition is served directly from your Site's Environment hostname at:

GET {envHost}/openapi.yml

This route authorises your API Key and returns a download filtered to only your key's assigned Workflows.

Authentication

Your API Key is scoped to a Site + Environment level, so individual Workflow route matching is not required.

Only Token-based API Keys are allowed for this endpoint. Cookie-based or Basic credentials will be rejected with Unauthorized.

See Token Authentication for details on how to authenticate correctly.

Permissions and Filtering

The returned specification includes only the Workflows assigned to your API Key (PermittedWorkflowKeys).

Response

The OpenAPI Specification is the open, language-agnostic standard for describing HTTP APIs.

If successful, this feature will allow you to receive a standards-compliant OpenAPI v3 definition (YAML) of your eligible HTTP endpoints, filtered to the Workflows permitted by your API Key, which can be downloaded as a file.
Background: OpenAPI definitions are commonly authored in YAML or JSON. YAML is widely used and supported.
For our feature, we chose the Content-Type is application/yaml; charset=utf-8. The response is a download (Content-Disposition: attachment) with a filename like "<siteKey>-<environmentKey>-openapi.yml".

Using this Feature

  1. Create or locate a Token-based API Key for your target Environment.
  2. Assign the Workflow(s) you want included in the specification to this API Key.
  3. Use your Environment's hostname. Flowgear will then the resolve the correct Site/Environment from the request host.
  4. Call the endpoint from any HTTP client, e.g. Postman:
    • Method: GET
    • Path: {envHost}/openapi.yml
    • Provide your API Key in the Authorization header (recommended) or as a path variable: ?auth-key=....