Reference · OpenAPI

OpenAPI 3.1 spec

The canonical, machine-readable description of the VisitorFlow REST API lives in the repo at docs/openapi.yaml. We publish the same file at the URL below so codegen tools and IDE plugins can pull straight from the docs site.

Latest spec

visitorflow.com/docs/api/openapi.yaml — always tracks the production deploy of main.
The same YAML is in the GitHub repo at docs/openapi.yaml.

Generating a client

# TypeScript (axios) using openapi-typescript-codegen
npx openapi-typescript-codegen \
  --input https://visitorflow.com/docs/api/openapi.yaml \
  --output ./src/visitorflow

# Python (httpx) using openapi-python-client
openapi-python-client generate \
  --url https://visitorflow.com/docs/api/openapi.yaml

Versioning

We bump the spec's info.version field on every release. Additive, backwards-compatible changes do not bump the URL prefix; breaking changes ship as /v2/ with a 12-month overlap. The OpenAPI document itself is included in every release tag, so you can pin to a known good revision.

Linting

We lint the spec on every PR with spectral against the default Stoplight ruleset. The CI job ships in .github/workflows/ci.yml and fails on any warning (rule violations are usually ergonomic — duplicate operationIds, missing descriptions, etc.).

Looking for narrative documentation? Start with the API reference or the webhooks guide.