OpenAPI 3.1.0

OpenAPI Specification

Machine-readable API definition in OpenAPI 3.1.0 format. Generate clients, validate requests, and explore with Swagger UI.

Download YAML Download JSON Swagger UI

42 endpoints

67 schemas

Auto-validated

Specification Details

OpenAPI Version

3.1.0

API Endpoints

Data Schemas

Formats

YAML & JSON

Available Servers

Productionhttps://api.justkalm.com/v1

Sandboxhttps://sandbox.justkalm.com/v1

Schema Preview

Excerpt from our OpenAPI specification showing endpoint and schema definitions.

openapi.yaml

openapi: 3.1.0
info:
  title: JustKalm API
  version: "2024-12-01"
  description: |
    The JustKalm API provides AI-powered luxury goods valuation.
    
    ## Authentication
    All requests require a Bearer token in the Authorization header.
    
    ## Versioning
    API version is specified in the URL path (/v1/).
  contact:
    name: API Support
    email: api@justkalm.com
    url: https://justkalm.com/support
  license:
    name: Proprietary
    url: https://justkalm.com/terms

servers:
  - url: https://api.justkalm.com/v1
    description: Production
  - url: https://sandbox.justkalm.com/v1
    description: Sandbox (test mode)

security:
  - bearerAuth: []

paths:
  /valuations:
    post:
      operationId: createValuation
      summary: Create a valuation
      tags:
        - Valuations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateValuationRequest'
      responses:
        '201':
          description: Valuation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValuationResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      
  schemas:
    CreateValuationRequest:
      type: object
      required:
        - sku
        - brand
        - category
      properties:
        sku:
          type: string
          description: Unique product identifier
          example: "HERMES-BIRKIN-35-BLACK"
        brand:
          type: string
          description: Brand name
          example: "Hermès"
        category:
          type: string
          enum: [bags, watches, jewelry, accessories]
        condition:
          type: string
          enum: [new, like_new, excellent, very_good, good, fair]
          default: excellent
          
    ValuationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Valuation'
          
    Valuation:
      type: object
      properties:
        id:
          type: string
          format: prefixed-id
          example: "val_abc123"
        sku:
          type: string
        estimated_value:
          $ref: '#/components/schemas/PriceRange'
        confidence:
          type: string
          enum: [high, medium, low]
        created_at:
          type: string
          format: date-time

Code Generation

Generate type-safe API clients from our OpenAPI spec.

OpenAPI Generator(Multi-language)

openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Swagger Codegen(Multi-language)

swagger-codegen generate -i openapi.yaml -l python -o ./client

oapi-codegen (Go)(Go)

oapi-codegen -package api -generate types,client openapi.yaml > api/client.go

openapi-typescript(TypeScript)

npx openapi-typescript openapi.yaml -o ./types/api.d.ts

Swagger UI

Run Swagger UI locally or embed in your documentation.

Run Swagger UI

# Docker: Run Swagger UI locally
docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://api.justkalm.com/openapi.json \
  swaggerapi/swagger-ui

# Or embed in your docs site
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<div id="swagger-ui"></div>
<script>
  SwaggerUIBundle({
    url: "https://api.justkalm.com/openapi.json",
    dom_id: '#swagger-ui',
    presets: [SwaggerUIBundle.presets.apis],
    layout: "BaseLayout"
  });
</script>

Schema Validation

Validate requests and responses against the schema using Spectral.

Spectral Validation

# Validate your OpenAPI spec with Spectral
npm install -g @stoplight/spectral-cli

# Create .spectral.yaml
extends: spectral:oas
rules:
  operation-operationId: error
  operation-tags: error
  oas3-schema: error
  info-contact: warn
  info-license: warn

# Run validation
spectral lint openapi.yaml

# Expected output:
# ✔ No results with errors or warnings

Best Practices

Pin to Versions

Use versioned schema URLs in CI/CD to prevent breaking changes from affecting builds.

Validate at Build

Run schema validation in CI to catch type mismatches before they reach production.

Build Type-Safe Integrations

Generate clients and validate requests with our OpenAPI spec.

View SDKs