Developer Center - Mili Express

REST API Documentation

Explore, test, and integrate with our RESTful endpoints. Full Swagger UI with interactive request builder and authentication support.

REST API

GraphQL API Documentation

Query exactly the data you need with our GraphQL API. Interactive playground with schema explorer and operation testing.

GraphQL

MCP Column

AI agents & MCP clients: setup, security profiles, approvals, and live tools for User + Developer servers.

MCP

Integration playbooks

Four self-contained paths. Each one is complete on its own: authenticate, quote, book, label or pay, track, and a test checklist. Stay on the path you opened.

Outbound shipping

Own-fleet pickup and delivery

Create a pickup or delivery order, print the local label, track, and receive events — own fleet, end to end. A rate quote is optional.

Pickup or delivery → local label → track → events

FLEET

Carrier labels

List shipping methods, get a rate, book a carrier label, download the PDF, and track the shipment.

Methods → rate → buy label → PDF → track

LABELS

Uniorder: one API for every shipment

Quote, create, print, track and cancel every shipment through one set of endpoints, whether the business delivers it or a carrier label is bought.

Quote → rate_id → order → label → track → cancel

UNIORDER

Quote and order in one flow

Quote self delivery and every label carrier service in one call, then create the order with the rate_id of the chosen rate.

Quote → rate_id → create order → buy label → cancel

QUOTE + ORDER

Shipping services

List the logistics company’s own services, estimate, place the order, pay, and track — end to end.

Services → estimate → create → pay → track

SERVICES

Storage and ship-out

Check goods into warehouse storage, pay, then ship stored items out on this path.

Store → pay → pick items → ship out → track

STORAGE

MCP Column

MCP 93 tools

Dedicated guide for AI agents and MCP clients: User vs Developer servers, least-privilege profiles, dry-run, human approvals, and the live tool catalog.

Profiles & scopes Human approvals Dry-run writes Developer MCP

Webhooks — Webhook Integration Guide

Receive real-time events from Superroute — orders, status changes, tracking updates. With signed payloads, automatic retries, and a built-in debugger.

WEBHOOKS

OTEP — Open Tracking Event Protocol

One Event. Infinite Journeys. — Self-delivery, third-party delivery and carrier shipments merge into one ordered event timeline per tracking number.

OTEP

Integration Updates Guide

What’s new in the API and webhooks — idempotent cancel, reconciliation feeds, v2 signatures, new events — with copy-paste examples. Everything is fully backward compatible.

NEW

Postman Collection

Always-current collection generated live from the API documentation — import it into Postman and start calling the API.

JSON

Order Status Dictionary & Flow

The complete order status dictionary and transition diagrams, generated live from the deployed code.

MARKDOWN

Tracking Event Codes

Customer-facing tracking event codes (pickup-side and delivery-side), OTEP mapping, common flows, and a guide to build your own tracking page with the public API.

TRACKING

Getting Started

Get Your API Token

Choose Your API

Use REST for standard CRUD operations, GraphQL for flexible data queries, or MCP to connect AI assistants directly to your logistics data.

Start Building

Open the interactive docs to test endpoints in your browser, then copy the code snippets into your application.

Authentication

All three APIs use the same Bearer token (obtained via the login endpoint). Some endpoints are public and require no authentication — including login, public tracking, and driver self-registration.

Obtain a token via the login endpoint:

                # POST /api/v1/user/login

                { "email": "you@example.com", "password": "••••••••" }

Request Header

Authorization: Bearer YOUR_ACCESS_TOKEN

REST Required for most endpoints. Login, public tracking, and driver self-registration are public (no token needed).

GQL Required for authenticated operations. Public operations (login, tracking) work without a token.

MCP Connection Bearer + optional X-MCP-Profile. Public tools work without a token; narrow profiles for agents.

Base URLs

REST API https://api.miliexpress.com/api
GraphQL https://api.miliexpress.com/api/graphql
MCP https://api.miliexpress.com/api/mcp

Which API Should I Use?

REST API

Standard CRUD operations, webhooks, order/route management

GraphQL

Flexible data fetching, custom reports, nested queries

MCP

AI assistant integration (Claude, Cursor, Copilot, etc.)

AI Integration

Give your AI assistant logistics superpowers. Connect via MCP for zero-code setup, call our API directly from your AI agent, or download the skill file for complete semantic guidance.

Available Capabilities

Public Tracking

Look up any package's delivery status, event timeline, and proof of delivery (signature/photo) by tracking number.

PUBLIC

Operation Events

Get the full audit trail for orders — who changed what status, when, where, with GPS coordinates and attached photos.

AUTH REQUIRED

Label Service

Get shipping quotes from carriers, create shipping labels, download label PDFs, cancel shipments, and submit end-of-day manifests.

AUTH REQUIRED

Local Delivery

Create delivery/pickup orders, build optimized multi-driver routes, and manage the full last-mile delivery workflow.

AUTH REQUIRED

END USER User MCP Server

For AI assistants used by your customers. Paste the config and your AI can track packages instantly — no coding required.

ENDPOINT

https://api.miliexpress.com/api/mcp

Available Tools (93 live tools)

track_package Track a package by its tracking number. Returns delivery status, trackin... PUBLIC

otep_tracking Get the unified OTEP (Open Tracking Event Protocol) timeline for a track... PUBLIC

get_capabilities List MCP tools available to the current connection, with risk level, req... PUBLIC

get_orders List orders with filtering and pagination. Returns order details includi... AUTH

get_order_detail Get full details of a specific order by ID, including address, status, p... AUTH

find_order Fuzzy-find orders across tracking number, external tracking, ref, recipi... AUTH

get_operation_events Get the full audit trail for orders — every status change, who performed... AUTH

create_order Create a delivery/pickup order. D=delivery (warehouse→customer), P=picku... AUTH

cancel_order Cancel an existing order by order ID. Only works for orders not yet deli... confirm

bulk_create_orders Create up to 100 delivery orders in one call. Returns a per-order succes... confirm

reroute_to_address Change the delivery address of an order that has not been picked up yet:... confirm

update_delivery_instruction Update only the delivery_instruction field on an existing order (PATCH).... AUTH

update_order_note Update only the internal note field on an existing order (PATCH). AUTH

update_time_window_by_refs Bulk-update delivery time windows (and optional schedule_date) for order... AUTH

hold_order Put an order on HOLD so it is not dispatched until release_order. HIGH-R... confirm

release_order Release an order from HOLD back to NEW_ORDER. HIGH-RISK: requires confir... confirm

propose_write Queue a write/high-risk tool for human approval instead of executing it.... AUTH

list_pending_approvals List pending MCP write approvals for this business (or mine_only). AUTH

approve_pending_write Approve and execute a pending write proposal. HIGH-RISK: requires confir... confirm

reject_pending_write Reject a pending write proposal without executing it. AUTH

get_routes List delivery routes with their status, assigned driver, and order count... AUTH

get_route_detail Get one route with its stop/order list. Prefer this over get_routes when... AUTH

get_drivers List drivers for the authenticated business (ids, names, capacity defaul... AUTH

get_driver_routes_today Orders assigned to a driver on a given date (defaults to today). Useful... AUTH

get_build_route_options List routing engines, balance modes, capacity types, and defaults before... AUTH

build_route Build/optimize a delivery route (POST /api/v3/client/build-route). HIGH-... confirm

order_snapshot One-call order context for support: order detail + operation events + pu... AUTH

list_exceptions List failed/returned/exception-like orders for a schedule date (default... AUTH

get_shipping_methods List available shipping carriers/methods. Returns IDs and names — use th... AUTH

get_shipping_rate Get a shipping cost quote. Dry-run — no label created. Returns rate opti... AUTH

create_shipping_label Book a shipment with a carrier and generate a shipping label with tracki... AUTH

quote_and_ship One-shot: rate across all enabled carriers, pick the best one by strateg... AUTH

compare_all_carriers Get rate quotes from every enabled carrier for the same shipment, in one... AUTH

search_address Search and resolve addresses by postal code or free-text query. Returns... AUTH

daily_digest One-call summary of today's logistics activity: total orders, by status,... AUTH

get_orders_summary Aggregate order metrics over a time window: counts by status, top carrie... AUTH

get_account_credits Get the authenticated customer's wallet balance, currency, and recent to... AUTH

get_warehouses List WMS warehouses available to the authenticated business. AUTH

get_inventory Query WMS inventory (POST /api/v1/wms/inventory). Pass filters supported... AUTH

list_datasets List custom datasets available to the business. AUTH

get_dataset Get one dataset by id (metadata/columns). AUTH

list_dataset_groups List groups inside a dataset. AUTH

search_dataset_records Search records across groups in a dataset (POST .../search). AUTH

list_alliances List alliances the authenticated business belongs to. AUTH

get_alliance Get one alliance by id. AUTH

list_alliance_members List members of an alliance. AUTH

list_accessible_clients List clients accessible via alliance partnerships. AUTH

quote_delivery Get the local delivery price for a shipment before creating the order (P... AUTH

print_local_label Get the printable label of a local delivery order as a base64 PDF, with... AUTH

bulk_create_orders_async Queue a large batch of delivery orders for creation (POST /api/v1/client... confirm

get_async_batch_result Read the status and per-order results of a batch queued with bulk_create... AUTH

get_shipping_detail Get the carrier shipping detail of a label order: tracking numbers, pric... confirm

download_shipping_label Download the label PDF of an order as base64 (POST /api/v1/shipping/getS... confirm

cancel_shipping_label Cancel (void) a carrier label with the carrier (POST /api/v1/labelservic... confirm

submit_shipping_information Submit the shipping information of one or more label orders to their car... confirm

end_of_day Close the day with the carriers: submit the shipping information of ever... confirm

uniorder_rate Quote one shipment across self delivery and, with quote_labels=true, eve... AUTH

uniorder_create Create an order at a rate_id from uniorder_rate (POST /api/v1/uniorder).... AUTH

uniorder_get Read one uniorder order in the uniorder shape (GET /api/v1/uniorder/{ord... AUTH

uniorder_label Get the label PDF of a uniorder order, base64 (GET /api/v1/uniorder/{ord... AUTH

uniorder_tracking Get the tracking timeline of a uniorder order (GET /api/v1/uniorder/{ord... AUTH

uniorder_cancel Cancel a uniorder order, self delivery or label (POST /api/v1/uniorder/{... confirm

uniorder_purchase_label Buy the carrier label of a uniorder label order that was kept without on... confirm

uniorder_rate_batch Quote up to 20 shipments in one call (POST /api/v1/uniorder/rate/batch).... AUTH

uniorder_create_batch Create up to 20 orders in one call, each at its own rate_id (POST /api/v... confirm

uniorder_rate_batch_async Queue up to 500 shipments to quote (POST /api/v1/uniorder/rate/batch-asy... AUTH

uniorder_create_batch_async Queue up to 500 orders to create, each at its own rate_id (POST /api/v1/... confirm

uniorder_job Read a queued uniorder batch and, once done, its results (GET /api/v1/un... AUTH

list_shipping_services List the shipping services the customer may order (GET /api/v1/customer/... AUTH

get_shipping_service_config Get one shipping service's order form: warehouses, surcharges, packaging... AUTH

estimate_shipping_order Estimate the price of a shipping order on a service (POST /api/v1/custom... AUTH

create_shipping_order Create a shipping order on a service (POST /api/v1/customer/shipping-ord... AUTH

pay_shipping_order Pay the full remaining balance of a shipping order from the customer wal... confirm

get_shipping_order Get one shipping order of the customer (GET /api/v1/customer/shipping-or... AUTH

list_shipping_orders List the customer's shipping orders on one service, paginated (GET /api/... AUTH

cancel_shipping_order Cancel a pending or confirmed shipping order of the customer (POST /api/... confirm

get_storage_order_config Get what a storage order form needs: warehouses, packaging, supplies, pi... AUTH

quote_storage_order Calculate the price of a storage order before creating it (POST /api/v1/... AUTH

create_storage_order Create a storage order (POST /api/v1/customer/storage-orders). Storage o... AUTH

pay_storage_order Pay a storage order from the customer wallet (POST /api/v1/customer/stor... confirm

get_storage_order Get one storage order of the customer, with can_edit, can_cancel and eac... AUTH

list_storage_orders List the customer's storage orders, paginated (GET /api/v1/customer/stor... AUTH

cancel_storage_order Cancel a storage order of the customer while its status allows it (POST... confirm

list_stored_packages List the customer's stored packages that can be shipped out: received, n... AUTH

list_shipout_services List the shipping services that ship out from a warehouse (GET /api/v1/c... AUTH

estimate_shipout Estimate the price of a ship-out (POST /api/v1/customer/shipout-orders/s... AUTH

create_shipout Create a ship-out of stored packages from one warehouse (POST /api/v1/cu... AUTH

pay_shipout Pay a priced ship-out from the customer wallet (POST /api/v1/customer/sh... confirm

get_shipout Get one ship-out of the customer with paid amount, remaining balance, ca... AUTH

list_shipouts List the customer's ship-outs, paginated (GET /api/v1/customer/shipout-o... AUTH

cancel_shipout Cancel a pending or confirmed ship-out and release its stored packages (... confirm

otep_client_tracking Get the OTEP timeline and details (addresses, dates, proof of delivery,... AUTH

otep_client_locker_storage Get the OTEP timeline (storage profile) and details of one of your locke... AUTH

// .mcp.json — ops agent with narrow profile
{
  "mcpServers": {
    "superroute": {
      "type": "url",
      "url": "https://api.miliexpress.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

DEVELOPER Developer MCP Server

For AI coding assistants (Claude Code, Cursor, etc.) that help you build Superroute integrations. Your AI can directly call APIs, test endpoints, and generate integration code.

ENDPOINT

https://api.miliexpress.com/api/mcp/developer

Available Tools (25 live tools)

track_package Track package by tracking number PUBLIC

get_operation_events Get order audit trail AUTH

get_shipping_methods List available carriers AUTH

get_shipping_rate Get shipping rate quote AUTH

create_shipping_label Create shipping label AUTH

get_shipping_label Get label details & download info AUTH

create_order Create delivery/pickup order AUTH

build_route Build optimized delivery routes AUTH

get_build_route_options Get available options for building routes: routing engines with their balance modes, capacity ty... AUTH

get_api_endpoints Search the complete Superroute REST API catalog (the same OpenAPI spec that powers /api/document... PUBLIC

get_graphql_operations Search the Superroute GraphQL catalog — every query and mutation, grouped by category, each with... PUBLIC

run_graphql_query Execute a query or mutation against the Superroute GraphQL endpoint (POST /api/graphql) and retu... AUTH

get_otep_tracking Get a package's tracking history as an OTEP (Open Tracking Event Protocol) document — the normal... PUBLIC

validate_otep_payload Run an OTEP document or event through the live conformance validator (POST /api/v1/otep/validate... PUBLIC

check_skill_update Check if a newer version of the Superroute AI integration skill file is available. Returns curre... PUBLIC

get_integration_guide Get integration guide PUBLIC

get_otep_guide Get the OTEP (Open Tracking Event Protocol) development guide — the What/When/Where/Why event mo... PUBLIC

get_webhook_guide Webhook integration guide PUBLIC

verify_webhook_signature Verify whether an incoming webhook signature is valid. Pass the raw payload (string or JSON obje... PUBLIC

test_webhook_delivery Fire a real, properly-signed test webhook from Superroute servers to a URL the developer provide... AUTH

get_webhook_settings Read the caller's own webhook configuration — every per-event callback URL, the behaviour flags,... AUTH

update_webhook_settings Self-serve update of the caller's webhook configuration (PUT /api/v1/webhook-settings). Partial:... AUTH

get_order_audit_timeline Chronological audit timeline of ONE order across every source: web actions, driver app scans, wa... AUTH

get_webhook_delivery_logs List recorded webhook delivery attempts for the caller — event type, target URL, HTTP status, at... AUTH

replay_webhook_delivery Re-send a webhook that was already logged, by delivery-log id (get the id from get_webhook_deliv... AUTH

// .mcp.json — connection Bearer preferred
{
  "mcpServers": {
    "superroute-dev": {
      "type": "url",
      "url": "https://api.miliexpress.com/api/mcp/developer",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Do not pass api_token in tool arguments after 2026-12-31. Use Authorization on the MCP connection.

User MCP is for managing Superroute with agents; Developer MCP is for building integrations. Full security model, profiles, and live tool list live in the MCP Column. Open MCP Column →

AI Tool Discovery Endpoints

Structured capability descriptions for AI agents, LLM tool-calling systems, and MCP clients. All endpoints are public, no authentication required.

PRIMARY AI Tools Manifest

Complete manifest with tool definitions, schemas, auth info, and workflows.

GET https://api.miliexpress.com/api/.well-known/ai-tools.json

Also available: /llms.txt

FORMAT Multi-Format Export

Get tool definitions in the format native to your AI platform.

# OpenAI function calling
GET https://api.miliexpress.com/api/ai/tools?format=openai

# Anthropic Claude tool_use
GET https://api.miliexpress.com/api/ai/tools?format=anthropic

# MCP tools/list
GET https://api.miliexpress.com/api/ai/tools?format=mcp

# LangChain StructuredTool
GET https://api.miliexpress.com/api/ai/tools?format=langchain

REST OpenAPI + AI Extensions

OpenAPI spec enriched with x-ai-* extensions (tool names, when to use, categories).

GET https://api.miliexpress.com/api/ai/tools/openapi

GQL GraphQL + AI Hints

GraphQL docs enriched with aiHints per operation (when to use, related workflows).

GET https://api.miliexpress.com/api/ai/tools/graphql

Quick Integration

Python (OpenAI SDK)

import requests, json
tools = requests.get(
  "https://api.miliexpress.com/api/ai/tools?format=openai"
).json()["tools"]

# Pass to OpenAI
response = client.chat.completions.create(
  model="gpt-4",
  messages=messages,
  tools=tools
)

Python (Claude SDK)

import requests, anthropic
tools = requests.get(
  "https://api.miliexpress.com/api/ai/tools?format=anthropic"
).json()["tools"]

# Pass to Claude
response = client.messages.create(
  model="claude-sonnet-4-20250514",
  messages=messages,
  tools=tools
)

Node.js (fetch)

const res = await fetch(
  "https://api.miliexpress.com/api/ai/tools?format=openai"
);
const { tools } = await res.json();

// Use with any LLM SDK
console.log(`Loaded ${tools.length} tools`);

Capabilities summary: For a lightweight overview (just categories and tool names), use GET https://api.miliexpress.com/api/ai/capabilities

AI Tools Playground

Test Superroute AI tools directly in your browser. Select a tool, fill in the parameters, and see the live API response.

Select Tool

track_package

Request Body (JSON)

Response

Click "Run" to execute the tool...

Build with REST or GraphQL

For developers building custom AI agents, chatbots, or programmatic integrations. Call our API directly from your code with full access to all logistics capabilities.

REST REST API Endpoints

# Track package (public)
GET https://api.miliexpress.com/api/v1/tracking/{number}

# Operation events
POST https://api.miliexpress.com/api/v1/tracking/operationevents

# Get shipping rate
POST https://api.miliexpress.com/api/v1/labelservice/rate

# Create shipping label
POST https://api.miliexpress.com/api/v1/labelservice/submitOrder

# Create delivery order
POST https://api.miliexpress.com/api/v1/client/orderCreate

# Build optimized route
POST https://api.miliexpress.com/api/v3/client/build-route

# Configure webhooks
PUT https://api.miliexpress.com/api/v1/webhook-settings

# Open tracking timeline (OTEP)
GET https://api.miliexpress.com/api/v1/otep/trackings/{number}

Full documentation

GQL GraphQL Operations

# Single endpoint
POST https://api.miliexpress.com/api/graphql

# Available operations
trackingPublic       ← Track package (public)
trackingOperationevents ← Operation events
labelserviceRate      ← Get shipping rate
labelserviceSubmitOrder ← Create shipping label
clientOrderCreate     ← Create delivery order
clientBuildRoute      ← Build optimized route
webhookSettingsUpdate ← Configure webhooks
otepTracking          ← Open tracking timeline (OTEP)

Full documentation

We recommend REST API for most AI integrations — it's simpler to debug and each endpoint is self-contained. Use GraphQL when you need flexible queries or want to fetch nested data in a single request.

Superroute AI Integration Skill

A comprehensive skill file with deep logistics domain knowledge — what each API does, when to use it, what parameters mean in real business context, how to interpret results, and how capabilities compose together.

Download Skill File (.md)

How to Use the Skill File

Claude Code

1 Download the file above
2 Place it in your project's .claude/skills/ directory
3 Type /integrate in Claude Code to start the interactive wizard

mkdir -p .claude/skills
cp superroute-ai-integration.md .claude/skills/

Cursor

1 Download the file above
2 Place it in your project's .cursor/rules/ directory
3 Cursor will automatically use it as context when you ask about Superroute integration

mkdir -p .cursor/rules
cp superroute-ai-integration.md .cursor/rules/

Other AI Tools

1 Download the file above
2 Paste the content into your AI tool's system prompt or knowledge base
3 The AI will use the semantic descriptions to guide integration

# Or paste into system prompt
cat superroute-ai-integration.md

Keep Your Skill File Up to Date

QUICK One-Command Upgrade

Download the latest skill file directly from the server. Overwrites your local copy with the newest version.

# Claude Code
curl -sS https://api.miliexpress.com/api/ai-skill -o .claude/skills/superroute-ai-integration.md

# Cursor
curl -sS https://api.miliexpress.com/api/ai-skill -o .cursor/rules/superroute-ai-integration.md

API Version Check API

Check the server for the latest version before downloading. Compare the hash with your local file to determine if an update is needed.

GET https://api.miliexpress.com/api/ai-skill/version

Response:
{ "version": "1.0.0", "hash": "abc123...", "download_url": "..." }

MCP Auto-Update via MCP

If you have the Developer MCP server connected, your AI assistant can check for updates using the check_skill_update tool. Pass your local file's MD5 hash to get an update_available boolean.

// Call via Developer MCP Server
{
  "method": "tools/call",
  "params": {
    "name": "check_skill_update",
    "arguments": { "current_hash": "your_local_file_md5_hash" }
  }
}

CRON Auto-Update Script (Cron / CI)

Add this script to your CI pipeline or cron job to keep the skill file always up to date automatically.

#!/bin/bash
# auto-update-skill.sh
SKILL_FILE=".claude/skills/superroute-ai-integration.md"
BASE_URL="https://api.miliexpress.com"

mkdir -p "$(dirname "$SKILL_FILE")"
LOCAL_HASH=$(md5sum "$SKILL_FILE" 2>/dev/null | cut -d' ' -f1)
SERVER_HASH=$(curl -s "$BASE_URL/api/ai-skill/version" | python3 -c "import sys,json; print(json.load(sys.stdin)['hash'])")

if [ "$LOCAL_HASH" != "$SERVER_HASH" ]; then
  curl -sS "$BASE_URL/api/ai-skill" -o "$SKILL_FILE"
  echo "Updated!"
fi

The skill file goes beyond API documentation — it teaches your AI assistant the business meaning of each parameter, how to interpret responses, and how to combine capabilities for complex logistics workflows.