Skip to main content

OpenAPI / Swagger

The Ozzie API is fully described in an OpenAPI 3.1 specification. You can use it to explore endpoints interactively, generate client libraries in any language, or wire up AI assistants that integrate with Ozzie automatically.

Live Swagger UI​

The interactive API explorer is available at:

https://api.ozzieapp.com/v1/docs

From the Swagger UI you can:

  • Browse all endpoints and their schemas
  • Try requests directly in the browser (click Authorize and enter your Bearer token)
  • View full request and response examples
  • Download the raw OpenAPI spec

Download the raw spec​

curl https://api.ozzieapp.com/v1/openapi.yaml -o ozzie-openapi.yaml

The spec is versioned alongside the API. The info.version field in the spec matches the changelog version.

Using the spec with code generators​

You can generate a type-safe API client in any language from the OpenAPI spec. The two most popular tools are openapi-generator-cli and swagger-codegen.

Generate a TypeScript client​

This example generates a fully typed TypeScript/Node.js client in three commands:

# Step 1: Install the generator (requires Java or Docker)
npm install -g @openapitools/openapi-generator-cli

# Step 2: Download the Ozzie spec
curl https://api.ozzieapp.com/v1/openapi.yaml -o ozzie-openapi.yaml

# Step 3: Generate the TypeScript client
openapi-generator-cli generate \
  -i ozzie-openapi.yaml \
  -g typescript-fetch \
  -o ./src/ozzie-client \
  --additional-properties=typescriptThreePlus=true,supportsES6=true

This creates a ./src/ozzie-client directory with typed interfaces, API classes, and a fetch-based HTTP layer.

Using the generated client:

import { Configuration, UsersApi, GoalsApi, ChatApi } from './ozzie-client';

const token = Buffer.from(
  `${process.env.OZZIE_CLIENT_ID}:${process.env.OZZIE_CLIENT_SECRET}`
).toString('base64');

const config = new Configuration({
  basePath: 'https://api.ozzieapp.com/v1',
  headers: { Authorization: `Bearer ${token}` },
});

const usersApi = new UsersApi(config);
const goalsApi = new GoalsApi(config);
const chatApi = new ChatApi(config);

// Fully typed — your IDE provides autocompletion and type checking
const { data: goal } = await goalsApi.getUserGoals({ userId: 'usr_4f8a1b2c3d' });
console.log(goal.goalName); // TypeScript knows this is a string

Generate a Python client​

openapi-generator-cli generate \
  -i ozzie-openapi.yaml \
  -g python \
  -o ./ozzie-python-client \
  --additional-properties=packageName=ozzie_client,projectName=ozzie-client
import ozzie_client
from ozzie_client.api import goals_api, chat_api

configuration = ozzie_client.Configuration(
    host="https://api.ozzieapp.com/v1",
    access_token=your_base64_token,
)

with ozzie_client.ApiClient(configuration) as api_client:
    goals = goals_api.GoalsApi(api_client)
    goal = goals.get_user_goals(user_id="usr_4f8a1b2c3d")
    print(goal.data.goal_name)

Generate a Go client​

openapi-generator-cli generate \
  -i ozzie-openapi.yaml \
  -g go \
  -o ./ozzie-go-client \
  --additional-properties=packageName=ozzie

Using Docker (no Java required)​

If you don't have Java installed, run the generator via Docker:

docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/ozzie-openapi.yaml \
  -g typescript-fetch \
  -o /local/src/ozzie-client

Using the spec with AI assistants​

AI coding assistants (GitHub Copilot, Cursor, Claude) can use the OpenAPI spec to understand the Ozzie API and generate integration code automatically. Add the spec to your project and reference it in your prompts:

Example: including the spec in your project

# Download to a standard location in your project
curl https://api.ozzieapp.com/v1/openapi.yaml -o docs/ozzie-openapi.yaml

Then in your AI assistant's context or system prompt:

Use the Ozzie API to implement user onboarding. The full OpenAPI spec is at docs/ozzie-openapi.yaml.
Create a user, submit their financial intake, and generate their plan in a single async function.

The AI assistant will read the spec and generate accurate, schema-compliant code.

Example: Cursor or Copilot in-editor

Add a comment at the top of your file pointing to the spec:

// Ozzie API spec: https://api.ozzieapp.com/v1/openapi.yaml
// Use: POST /users/{user_id}/plan to generate a financial plan

Most modern AI tools will fetch and interpret the linked spec automatically.

Spec features​

The Ozzie OpenAPI spec includes:

  • Full request and response schemas for every endpoint
  • Enum values for all string fields (cadence, goal_type, status, etc.)
  • Error response schemas for all documented error codes
  • Realistic example values in every example annotation
  • description fields on every property — suitable for AI parsing and code generation
  • Authentication documented as http scheme with bearer format

Keeping the spec up to date​

The spec reflects the current API version. When new endpoints or fields are added (see the Changelog), the spec is updated simultaneously. You can automate spec refresh in your CI pipeline:

# .github/workflows/refresh-spec.yml (run weekly)
- name: Refresh Ozzie OpenAPI spec
  run: curl -sf https://api.ozzieapp.com/v1/openapi.yaml -o docs/ozzie-openapi.yaml

- name: Regenerate TypeScript client
  run: |
    openapi-generator-cli generate \
      -i docs/ozzie-openapi.yaml \
      -g typescript-fetch \
      -o src/ozzie-client
tip

Pin your generated client to a specific spec version by downloading the versioned spec URL: https://api.ozzieapp.com/v1/openapi.yaml?version=1.0.0. This prevents your generated code from changing unexpectedly when the API is updated.