OpenAPI 3.1 spec at /v1/openapi.json

The full Public API surface is described in an OpenAPI 3.1 spec served at https://api.turtini.com/v1/openapi.json. No auth required to read the spec — the endpoints themselves still need a Bearer key.

What the spec covers:
• Every read + write endpoint (contacts, articles, events, accounts, opportunities, auth/verify, org-context query)
• Required scopes per endpoint
• Request/response schemas with field types, required fields, enums, length limits
• Pagination parameters
• Idempotency-Key header documentation
• Error envelope shape

Why this matters:
• Postman / Insomnia / Stoplight import the spec directly — instant API browser, request templates, mock servers
• Language SDK codegen via openapi-generator-cli works for 50+ languages out of the box
• AI tooling (LLM agents, copilots) can introspect the surface without us hand-feeding it
• Diff the spec between deploys to spot breaking changes early

Quickstart — Postman:
1. Open Postman → Import → Link
2. Paste https://api.turtini.com/v1/openapi.json
3. Set the Bearer auth token at the collection level (your turtini_<key>)
4. Browse the API — every endpoint has request templates, parameter docs, and example responses

Quickstart — generate a Python client:
npx @openapitools/openapi-generator-cli generate \
-i https://api.turtini.com/v1/openapi.json \
-g python \
-o turtini-python

Other supported generators include: ruby, go, rust, csharp, java, kotlin, swift, php, dart, elixir.

Sync guarantee: the spec is generated from the same handler code that backs the endpoints. When we add an endpoint or change a field, the spec changes in lockstep — there's no out-of-band documentation to drift.

Versioning: the spec carries info.version (currently 1.0.0). We bump the major when we make a breaking change to any existing endpoint; new endpoints + new optional fields are minor bumps.

Cache: the spec is served with public, max-age=300 — 5-minute edge cache via Cloudflare. Refreshes within minutes of a deploy.