OpenAPI spec

OpenAPI specification

The whole API as a machine-readable document:

GET https://api.havnly.ai/functions/v1/openapi

Public and unauthenticated — it describes how to authenticate, so needing a key to read it would be a circle.

Generate a client

Rather than writing HTTP calls by hand:

# TypeScript
npx openapi-typescript https://api.havnly.ai/functions/v1/openapi -o havnly.d.ts
 
# Python, Java, Go, C#, and about forty others
openapi-generator-cli generate \
  -i https://api.havnly.ai/functions/v1/openapi \
  -g python -o ./havnly-client

It is OpenAPI 3.1.0, so use a generator that supports 3.1. Most that only speak 3.0 will still read it, but may drop examples and some schema keywords.

You can also paste the URL into Postman, Insomnia, Bruno or Stoplight and have the whole collection appear.

What is in it

  • Every path, method and parameter, with operationIds that make generated method names readable — createRequest, setDates, cancelBooking.
  • Both security schemes: Authorization: Bearer and x-api-key.
  • The request schemas, including which fields are required — the same set the API enforces.
  • The shared error shape, and the 401 / 403 / 429 / 500 every authenticated call can return.
  • Idempotency-Key marked on the writes where it matters, so a generated client exposes it as a parameter rather than hiding it.

Tags split the two halves of the market: Requests, Placements, Money and Events for carriers, Providers for housing companies. Your key decides which calls will actually answer you.

It is served from the platform

Not from this documentation site. The spec is generated by the same deployment that serves the API, so it cannot drift into describing a version that was released from a different commit. If the API changed this morning, the spec changed with it.

The info.version is a date — 2026-09-22 — and moves when the surface changes. It is cached for five minutes.

What it does not describe

Webhook payloads. Those are documented in Webhooks and Events. The bodies we post to your endpoint are not requests to this API, so they are not paths in this document.

Business rules. A spec can say move_in is a date. It cannot say a placement runs for at least thirty days, that the budget ceiling is hard unless you ask for it not to be, or that cancelling a paid placement is refused until a refund has been requested. Those live in the rest of these pages, and they are the part that decides whether an integration works.

Usage & diagnosticsErrors