name: integrating-with-owm
description: Use when integrating with OWM (OKS World Model) APIs for warehouse operations - bins, operations, flows, stations, tiles. Dynamically fetches current API structure from source code.

Integrating with OWM

OWM (OKS World Model) is a FastAPI-based warehouse operations system managing bins, operations, flows, stations, and tiles.

Quick Reference

API Base: /api/v1
JSON Casing: camelCase

Before Implementing

Always fetch current API structure from source. The API evolves - don't rely on cached knowledge.

Option 1: GitHub MCP Tools (Preferred)

Use GitHub MCP tools to fetch routing and schema files:

Repository: rapyuta-robotics/rapyuta-owm
API Location: rapyuta_owm/api/api_v1/

Key files per endpoint:
- {endpoint}/routing.py  → FastAPI routes, HTTP methods, query params
- {endpoint}/schemas.py  → Pydantic request/response models

Example - fetch bins endpoint:

mcp__github__get_file_contents:
  owner: rapyuta-robotics
  repo: rapyuta-owm
  path: rapyuta_owm/api/api_v1/bins/routing.py

mcp__github__get_file_contents:
  owner: rapyuta-robotics
  repo: rapyuta-owm
  path: rapyuta_owm/api/api_v1/bins/schemas.py

Option 2: Local Files

If you have local access to the repository:

# List all API endpoints
ls rapyuta-owm/rapyuta_owm/api/api_v1/

# Read specific endpoint routing
cat rapyuta-owm/rapyuta_owm/api/api_v1/bins/routing.py
cat rapyuta-owm/rapyuta_owm/api/api_v1/operations/routing.py

Option 3: OpenAPI Spec

If the service is running, fetch the OpenAPI spec:

curl http://localhost:8000/openapi.json

Endpoint Directory

Common Patterns

Pagination: All list endpoints return Page[Model] with items, total, page, size

Bulk Operations: POST endpoints accept arrays (max 500), return { created: [...], errorIndices: [...] }

Version Sync: Use ?versionGt=N for incremental fetching

Trace Context: Operations accept traceContext: { traceparent, tracestate } for distributed tracing

Cross-References

• @integrating-with-wms - WMS container/order/inventory APIs
• @integrating-backend-services - RTK Query patterns for frontend