Three Ways to Explore the MES AI REST API

MES AI exposes a versioned REST API under /api/v1/ that covers every domain the platform manages — WIP tracking, inventory, equipment, dispatch, ERP integration, plugins, and more. Before writing a client, building an integration, or testing a new endpoint, it helps to know exactly what the server is offering. FastAPI generates live, accurate API documentation from the code itself, so the docs are always in sync with the running server.

There are three ways to access that documentation, and each one serves a different purpose. For these examples, the MES server is running on localhost port 8082.

1. Swagger UI — Interactive Exploration

The Swagger UI is the fastest way to understand and experiment with the API. With the MES AI server running, open a browser and navigate to:

http://localhost:8082/api/v1/docs

The page lists every endpoint, grouped by domain tag — Physical Model, WIP Tracking, Inventory, Performance Analysis, and so on. Each endpoint can be expanded to see its HTTP method, path, path and query parameters, and the full request and response schemas derived from the Pydantic models in the server code.

The key feature of Swagger UI is the Try it out button. Clicking it on any endpoint opens an inline form where you can fill in parameters and a request body, then execute the call directly from the browser. The page shows the full curl command, the request URL, the HTTP response code, and the response body. This makes it practical for:

• Verifying that an endpoint behaves as expected after a code change.
• Checking what a response payload looks like before writing deserialization code.
• Exploring unfamiliar endpoints without leaving the browser.
• Testing authentication flows — paste a JWT into the Authorize dialog and all subsequent requests include it.

Note that most endpoints require a valid JWT. Use the POST /api/v1/auth/local/login endpoint first to obtain an access token, then click Authorize at the top of the page and paste it in as a Bearer token.

2. ReDoc — Readable Reference Documentation

ReDoc renders the same OpenAPI specification as a clean, three-panel reference document:

http://localhost:8082/api/v1/redoc

The left panel shows a collapsible table of contents organized by tag. The center panel shows the selected endpoint's description, parameters, and request/response schemas. The right panel shows example payloads.

Unlike Swagger UI, ReDoc is read-only — there is no way to execute requests from the page. What it offers instead is a better reading experience for longer sessions. The schema presentation is more compact, deeply nested objects are rendered clearly, and the fixed navigation makes it easy to jump between domains without losing context. ReDoc is well-suited for:

• Onboarding a new developer to the API surface.
• Reviewing the full set of fields on a complex schema like a WIP unit or a production order.
• Generating printed or PDF API reference documentation from a browser print dialog.
• Sharing a link to a specific endpoint with a colleague.

3. OpenAPI JSON — Machine-Readable Specification

The raw OpenAPI 3.1 specification is available as JSON at:

http://localhost:8082/api/v1/openapi.json

This endpoint returns the complete specification document that both Swagger UI and ReDoc use as their data source. Accessing it directly is useful when you need to work with the spec programmatically rather than through a browser:

• Client generation — tools like openapi-generator or openapi-typescript-codegen can consume this file and produce typed client libraries in TypeScript, Python, Go, or other languages. The MES AI React clients use hand-written API modules, but a generated client is a viable starting point for new integrations.
• Postman and Insomnia — both tools can import an OpenAPI JSON file to create a full collection of requests with pre-populated parameters and schemas. Point either tool at the URL or download the file and import it directly.
• Linting and contract testing — tools like spectral can validate the spec against a style guide, and contract-testing frameworks can use it to verify that the running server conforms to a committed spec snapshot.
• Documentation pipelines — the JSON file can be fed into documentation generators or published to a developer portal alongside other API specifications in a multi-service environment.

To download the file, use curl or any HTTP client:

curl http://localhost:8082/api/v1/openapi.json -o mes_ai_openapi.json

Which One to Use

All three views are generated from the same source of truth — the Pydantic schemas and FastAPI route decorators in the server code — so they are always consistent with the running server. The right view depends on what you are doing:

• Use Swagger UI when you want to run a quick test or explore behavior interactively.
• Use ReDoc when you want to read the API as a reference document or share it with a colleague.
• Use the OpenAPI JSON when you need to import the spec into a tool, generate client code, or automate contract validation.

Please send any comments or suggestions to point85.apps@gmail.com.