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

You can optionally include runtimeVersion to select the Workflow runtime:

GET {envHost}/openapi.yml?runtimeVersion=1
GET {envHost}/openapi.yml?runtimeVersion=2

If you do not provide runtimeVersion, Flowgear defaults to runtimeVersion=1.

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 and the returned definition is further limited to its assigned Workflows.

Only current Service token API Keys are intended for this endpoint. Cookie, Delegate MCP user, and legacy credentials are rejected.

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, 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 resolve the correct Site/Environment from the request host.
  4. Call the endpoint from any HTTP client, for example, Postman:
    • Method: GET
    • Path: {envHost}/openapi.yml
    • Optional query parameter: runtimeVersion=1 (v1 Runtime Workflows, default) or runtimeVersion=2 (v2 Runtime Workflows).
    • Provide your API Key in the Authorization: Bearer <token> header. The legacy auth-key query parameter is also supported, but avoid query-string credentials because URLs can be logged.