{"id":"openapi-insurance-crm-spec-tour","slug":"insurance-crm-openapi-3-1-spec-tour","title":"A Guided Tour of the unLocked CRM OpenAPI 3.1 Spec","excerpt":"Walk through every section of the live OpenAPI 3.1 document — servers, security schemes, tags, paths, components, and webhook definitions — and learn what each block unlocks for integrators.","content":"<p>The unLocked CRM OpenAPI 3.1 specification is the single source of truth for every endpoint, schema, and webhook in the platform. If you can read it, you can integrate. Here's a guided tour.</p>\n\n<h2>Where to Find It</h2>\n<p>The live spec is published at <code>/openapi.json</code> and surfaced via <code>/.well-known/api-catalog</code> (RFC 9727). It's regenerated on every deploy so it never drifts from production.</p>\n\n<h2>The Eight Sections That Matter</h2>\n<ol>\n<li><strong>info</strong> — version, contact, license, and a description that doubles as the developer landing page.</li>\n<li><strong>servers</strong> — production, sandbox, and regional URLs with environment variables baked in.</li>\n<li><strong>tags</strong> — 16 logical groupings (Contacts, Pipelines, Policies, Commissions...) that drive client SDK organization.</li>\n<li><strong>paths</strong> — every endpoint with method, summary, parameters, request body schema, and per-status response shapes.</li>\n<li><strong>components.schemas</strong> — every object the API returns, fully typed and reusable via <code>$ref</code>.</li>\n<li><strong>components.securitySchemes</strong> — <code>x-api-key</code> and OAuth 2.0 Bearer flows declared so codegen tools wire auth automatically.</li>\n<li><strong>components.parameters</strong> — shared pagination, filtering, and tracing headers.</li>\n<li><strong>webhooks</strong> — OpenAPI 3.1's first-class webhook support documents every event payload your endpoint will receive.</li>\n</ol>\n\n<h2>Why 3.1 (Not 3.0) Matters</h2>\n<p>OpenAPI 3.1 aligns with JSON Schema 2020-12, supports webhooks natively, and lets us express nullable types correctly. Tools like Stainless, Speakeasy, Fern, and Hey API all consume 3.1 to generate idiomatic SDKs in TypeScript, Python, Go, Ruby, and Kotlin.</p>\n\n<h2>What to Do Next</h2>\n<p>Import the spec into Postman, generate a client with <code>npx @hey-api/openapi-ts</code>, or paste the URL into ChatGPT and ask it to write the integration for you. The spec is the contract — everything else is downstream.</p>","category":"Reference","featureLink":"/mcp-server","cluster":"mcp-api","date":"2026-11-18","lastModified":"2026-11-18","readTime":"8 min","author":"unLocked Team"}