OpenAPI contract

The public OpenAPI 3.0 document is the machine-readable contract for Hodoflow's generated JSON:API surface plus reviewed manual definitions for token exchange and webhook ingestion. Use it to discover paths, inspect request and response schemas, configure a raw viewer, or generate a client inside your own build. It is public and contains no tenant data or credentials.

It is not a catalog of every HTTP route Hodoflow serves. Read the coverage boundary before treating it as an application-wide API definition.

What the document covers

Every path in the document is already absolute from the application origin: generated resource paths include /api/json/v1, while the reviewed manual paths include /api/v1. The public developer-host copy sets servers[0].url to the application origin, not to the developer portal and not to an origin with another API prefix. Join the server and path exactly once:

servers[0].url                  https://hodoflow.com
path                            /api/json/v1/workflows
request URL                     https://hodoflow.com/api/json/v1/workflows

Do not append /api/json/v1 to the server URL before passing the document to a viewer or generator; doing so creates a doubled path.

Download the release-matched document

Download the document from the same release as the portal:

export HODOFLOW_DEVELOPER_URL=https://developer.hodoflow.com
curl -fsS "$HODOFLOW_DEVELOPER_URL/openapi.json" -o hodoflow-openapi.json

Check the advertised API origin and JSON:API contract version before using it:

jq '{openapi, version: .info.version, servers}' hodoflow-openapi.json

A production document reports OpenAPI 3.0.0, JSON:API contract version v1, and one application-origin server. The v1 value identifies this API surface; it is not a release number and does not select the GraphQL schema version.

The document served at /openapi.json is the recommended input for external tools because its server is explicit. The application also exposes a discovery copy at /api/json/v1/open_api, but a client fetching that copy already needs to know the application origin.

Read an operation

Paths map an HTTP method to its stable operationId, purpose, parameters, body, responses, errors, and product-facing tag. For example, inspect the list-workflows operation with:

jq '.paths["/api/json/v1/workflows"].get' hodoflow-openapi.json

Interpret the important pieces as follows:

The top-level bearer scheme applies to authenticated operations. For JSON:API, safe methods require api_read and unsafe methods require api_write; x-hodoflow.scope carries that exact decision. Webhook ingestion requires webhooks. Token exchange has no bearer requirement because it produces the bearer token.

Parameters are operation-specific. If page, a filter field, or a sort field does not appear on an operation, do not send it. In particular, do not assume that every collection paginates or that omission implies a default page size. See JSON:API conventions for media types, filter syntax, idempotency, response headers, and the error envelope.

Generate a client safely

Hodoflow does not currently publish an official SDK. A client generated from this document is your build artifact, so pin the downloaded input and review the generator output before shipping it.

Use a generator that supports all of these OpenAPI 3.0 features:

• deepObject query serialization for filter, page, and sparse fieldsets;
• application/vnd.api+json request and response bodies;
• referenced schemas, nullable unions, enums, patterns, and numeric bounds;
• distinct create and update input schemas; and
• response bodies whose top-level JSON:API shape is {data, included, meta}.

Every public HTTP operation has a unique stable operationId and reviewed summary. Still wrap generated client methods behind names you control: generator naming and serialization choices remain build-tool behavior rather than part of Hodoflow's runtime contract.

Also verify how your generator handles recursive filter objects and additionalProperties. A generated method that flattens a deep-object filter into an ordinary string will not send the same request the schema describes. Compare one generated collection request with the bracketed examples in the first API request before adopting it broadly.

Generating from this file can create helpers for token exchange and webhook ingestion. GraphQL remains outside OpenAPI and uses the GraphQL SDL. Do not move either manual HTTP endpoint under the JSON:API v1 base path.

Detect contract changes

Keep the exact OpenAPI file used to generate a released client. On upgrade, download the next file, normalize both documents, and review the diff before regenerating:

jq -S . hodoflow-openapi.json > hodoflow-openapi.sorted.json
jq -S . hodoflow-openapi.next.json > hodoflow-openapi.next.sorted.json
diff -u hodoflow-openapi.sorted.json hodoflow-openapi.next.sorted.json

Review path and method removals, newly required inputs, narrower enums or bounds, schema type changes, and response-shape changes first. Additive paths, optional fields, and response properties can still affect strict decoders, so exercise the generated client against representative responses after every regeneration.

At runtime, record x-api-version and x-request-id from responses. The first confirms which JSON:API contract served the request; the second is the correlation identifier to retain when diagnosing a mismatch with support.

Choose the matching human reference

Use the curated API reference for a browsable rendering with guidance, or the secondary raw Swagger viewer to inspect the document directly. Use JSON:API conventions for behavior shared across resource operations, and the task guides for a complete request, expected response, permissions, and recovery steps. The machine document defines the wire shape; the human pages explain how to use it safely.