# Superroute

> Superroute is a multi-tenant logistics and delivery management platform providing APIs for order management, route optimization, package tracking, shipping label services, warehouse management, and more.

## API Documentation

- [OpenAPI Specification (REST)](/docs/api-docs.json)
- [GraphQL Documentation](/docs/graphql-swagger-docs.json)
- [GraphQL Introspection](/api/graphql/schema)
- [Swagger UI](/api/documentation)
- [GraphQL Playground](/api/graphql/documentation)
- [Developer Center](/api/developer-center)
- [MCP Setup Guide](/api/mcpguide)

## AI Tool Discovery

- [AI Tools Manifest (JSON)](/api/.well-known/ai-tools.json): Full structured manifest with tool definitions, input/output schemas, authentication info, and workflow descriptions.
- [AI Capabilities Summary](/api/ai/capabilities): Lightweight overview of categories and tool counts.
- [OpenAI Function Calling Format](/api/ai/tools?format=openai): Tools in OpenAI function-calling schema.
- [Anthropic Tool Use Format](/api/ai/tools?format=anthropic): Tools in Claude tool_use schema.
- [MCP Tools Format](/api/ai/tools?format=mcp): Tools in MCP tools/list response format.
- [LangChain Tools Format](/api/ai/tools?format=langchain): Tools in LangChain StructuredTool schema.
- [OpenAPI with AI Extensions](/api/ai/tools/openapi): OpenAPI spec enriched with x-ai-* metadata.
- [GraphQL with AI Hints](/api/ai/tools/graphql): GraphQL docs enriched with aiHints per operation.

## MCP Servers (Model Context Protocol)

### User MCP Server
- Endpoint: `/api/mcp`
- Protocol: JSON-RPC 2.0 over HTTP POST
- Authentication: Optional Bearer token for authenticated tools
- Public tools: track_package
- Authenticated tools: create_order, get_orders, get_order_detail, cancel_order, get_routes, get_operation_events, get_shipping_methods, get_shipping_rate, create_shipping_label, search_address

### Developer MCP Server
- Endpoint: `/api/mcp/developer`
- Protocol: JSON-RPC 2.0 over HTTP POST
- Authentication: Per-tool via api_token parameter
- Tools: track_package, get_operation_events, get_shipping_methods, get_shipping_rate, create_shipping_label, get_shipping_label, create_order, get_integration_guide

## Authentication

Most API endpoints require a Bearer token. Get one by calling:

```
POST /api/v1/user/login
Content-Type: application/json

{"email": "your@email.com", "password": "your_password"}
```

The response contains an `access_token` valid for 1 week. Use it in the Authorization header:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Key API Categories

### Tracking (Public)
- `GET /api/v1/tracking/{trackingNumber}` - Track a package by tracking number

### Orders (Authenticated)
- `POST /api/v1/client/orderCreate` - Create a delivery order
- `POST /api/v1/client/batchOrderCreate` - Batch create orders
- `GET /api/v1/orders/list` - List orders
- `GET /api/v1/orders/{orderId}` - Get order detail
- `PATCH /api/v1/orders/{orderId}` - Modify order
- `GET /api/v1/orders/{orderId}/cancel` - Cancel order

### Shipping Labels (Authenticated)
- `POST /api/v1/labelservice/getShippingMethodList` - List carriers
- `POST /api/v1/labelservice/rate` - Get shipping rate quote
- `POST /api/v1/labelservice/submitOrder` - Create shipping label
- `POST /api/v1/labelservice/getShippingDetail` - Get label details
- `POST /api/v1/labelservice/cancelShippingLabel` - Cancel label

### Routes (Authenticated)
- `GET /api/v1/client/routes` - List routes
- `POST /api/v1/client/build-route` - Build delivery route
- `POST /api/v1/client/routes/optimize` - Optimize route

### OCR (Authenticated)
- `POST /api/v1/ocr/label` - Parse shipping label image
- `POST /api/v1/ocr/scan-codes` - Scan barcodes/QR codes

### Warehouse (Authenticated)
- `GET /api/v1/wms/warehouse` - List warehouses
- `POST /api/v1/wms/inventory` - Query inventory
- `POST /api/v1/inventories/stockin` - Stock inbound
- `POST /api/v1/inventories/stockout` - Stock outbound

## Common Workflows

### Ship a Package
1. `get_shipping_methods` - Get available carriers
2. `get_shipping_rate` - Compare rates (optional)
3. `create_shipping_label` - Book shipment and generate label
4. `track_package` - Monitor delivery

### Local Delivery
1. `create_order` - Create delivery order
2. `build_route` - Assign to driver with optimized route
3. `track_package` - Monitor delivery status

### Batch Import
1. `batch_create_orders` - Create all orders in one call
2. `build_route` - Plan delivery routes

## Optional

- [AI Integration Skill File](/api/ai-skill): Download a comprehensive integration guide for AI coding assistants (Claude Code, Cursor, Windsurf, etc.)
- [AI Tools Playground](/api/ai/playground): Interactive browser-based tool testing