MESkit public website

REST API — Programmatic Access

Access every MES operation programmatically. Auto-generated REST endpoints with API key auth, OpenAPI spec, and webhook subscriptions.

Last updated: March 7, 2026

Summary

What the REST API provides.

Summary

The MESkit REST API exposes every tool in the MES registry as a REST endpoint. It is auto-generated from the tool definitions — no custom API routes needed. Authentication uses API keys with scoped permissions. An OpenAPI 3.0 spec is generated automatically from the Zod schemas. Webhooks notify external systems when key production events occur.

Authentication

API key-based access.

All API requests require an Authorization: Bearer <api-key> header. The API key is looked up by hash in the api_keys table, which stores:

name — A label for the key (e.g., "ERP Integration")
key_hash — SHA-256 hash of the plaintext key
scopes — Array of tool names this key can access (e.g., ["list_lines", "move_unit"])
is_active — Toggle to disable without deleting
last_used_at — Updated on each request

The plaintext API key is only shown once at creation time. After that, only the hash is stored. If you lose the key, create a new one and deactivate the old one.

Calling tools

POST /api/tools/{toolName}

Every registered tool is available at /api/tools/{toolName}.

# Create a manufacturing line
curl -X POST https://your-meskit.com/api/tools/create_line \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Assembly"}'

# List all lines
curl -X POST https://your-meskit.com/api/tools/list_lines \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}'

# Move a unit to the next step
curl -X POST https://your-meskit.com/api/tools/move_unit \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"unit_id": "uuid-here"}'

The request body matches the tool's Zod schema exactly. Validation errors return a 400 response with details about which fields failed.

Pagination

Cursor-based pagination for list endpoints.

List endpoints support pagination via query parameters:

# First page (10 items)
POST /api/tools/list_lines?limit=10

# Next page
POST /api/tools/list_lines?limit=10&cursor=last-id-from-previous

The response includes a next_cursor field when more results are available. Pass it as the cursor parameter to fetch the next page.

OpenAPI spec

Auto-generated API documentation.

The OpenAPI 3.0 specification is available at /api/openapi.json. It is auto-generated from the tool registry's Zod schemas and includes:

All tool endpoints with request/response schemas
Bearer authentication scheme
Parameter descriptions from Zod schema metadata

Import the spec into tools like Postman, Swagger UI, or API clients for interactive testing.

Webhooks

Real-time notifications for external systems.

Supported events

Event	Trigger	Payload includes
`unit_moved`	Unit advances to next route step	Unit data, new step, completion status
`quality_event`	Quality event is recorded	Event type, result, defect code, workstation
`machine_status_change`	Machine status is updated	Machine data, old status, new status

Webhook subscriptions

Subscriptions are stored in the webhook_subscriptions table:

url — The endpoint to receive webhook deliveries
events — Array of event types to subscribe to (or * for all)
secret — Used to sign payloads with HMAC SHA-256
is_active — Toggle to pause without deleting

Signature verification

Each webhook delivery includes headers for verification:

X-Webhook-Signature — sha256={hmac}
X-Webhook-Event — The event type

// Verify webhook signature (Node.js)
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(req.body)
  .digest('hex');
const valid = signature === expected;

Key facts and FAQ

Quick reference.

Key facts

Every MES tool is automatically exposed as a REST endpoint — no custom API code needed.
Authentication uses API keys with scoped permissions stored in the database.
The OpenAPI 3.0 spec is auto-generated from Zod schemas in the tool registry.
Webhooks fire on key events: unit_moved, quality_event, machine_status_change.
Webhook payloads are signed with HMAC SHA-256 for verification.
List endpoints support cursor-based pagination with limit and cursor parameters.
The API uses the same tool layer as the UI and chat — identical behavior and validation.

Mini FAQ

How do I get an API key?

API keys are stored in the api_keys table in Supabase. Each key has a name, scoped permissions (which tools it can access), and an active/inactive flag. Keys are hashed before storage — the plaintext key is only shown once at creation time.

What does the API key authenticate?

The API key identifies a user and scopes their access. When a request arrives, the key hash is looked up, the user is identified, and a JWT-scoped Supabase client is created. All RLS policies apply as if the user were logged in through the UI.

How do I call a tool via the API?

Send a POST request to /api/tools/{toolName} with the tool input as JSON body and your API key in the Authorization header. Example: POST /api/tools/list_lines with Authorization: Bearer your-api-key.

What events trigger webhooks?

Three events trigger webhooks: unit_moved (when a unit advances in its route), quality_event (when a quality event is recorded), and machine_status_change (when a machine status is updated). Subscriptions can filter by event type or use * for all.

How do I verify webhook signatures?

Each webhook delivery includes an X-Webhook-Signature header with a sha256= prefix. Compute HMAC SHA-256 of the request body using your webhook secret and compare. This verifies the payload was sent by MESkit and was not tampered with.

Getting Started View on GitHub