DEVELOPER

Developer Center

Everything you need to integrate with our platform — REST, GraphQL, and MCP.

REST /api/v1/orders JSON
GQL query { orders { id } } GraphQL
MCP track_package(number) Tool
Developer Center
REST Docs GraphQL Docs MCP Guide Webhooks Home

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

MCP Column

MCP 47 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

Getting Started

1
Get Your API Token

Log in and go to Settings → API Keys to generate your personal access token.

2
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.

3
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.superlabel.ca/api
  • GraphQL https://api.superlabel.ca/api/graphql
  • MCP https://api.superlabel.ca/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.superlabel.ca/mcp
Available Tools (47 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
// .mcp.json — ops agent with narrow profile { "mcpServers": { "superroute": { "type": "url", "url": "https://api.superlabel.ca/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.superlabel.ca/mcp/developer
Available 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_integration_guide Get integration guide PUBLIC
get_webhook_guide Webhook integration guide PUBLIC
// .mcp.json — connection Bearer preferred { "mcpServers": { "superroute-dev": { "type": "url", "url": "https://api.superlabel.ca/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.superlabel.ca/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.superlabel.ca/api/ai/tools?format=openai # Anthropic Claude tool_use GET https://api.superlabel.ca/api/ai/tools?format=anthropic # MCP tools/list GET https://api.superlabel.ca/api/ai/tools?format=mcp # LangChain StructuredTool GET https://api.superlabel.ca/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.superlabel.ca/api/ai/tools/openapi
GQL GraphQL + AI Hints

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

GET https://api.superlabel.ca/api/ai/tools/graphql
Quick Integration
Python (OpenAI SDK)
import requests, json tools = requests.get( "https://api.superlabel.ca/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.superlabel.ca/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.superlabel.ca/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.superlabel.ca/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
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.superlabel.ca/api/v1/tracking/{number} # Operation events POST https://api.superlabel.ca/api/v1/tracking/operationevents # Get shipping rate POST https://api.superlabel.ca/api/v1/labelservice/rate # Create shipping label POST https://api.superlabel.ca/api/v1/labelservice/submitOrder # Create delivery order POST https://api.superlabel.ca/api/v1/client/orderCreate # Build optimized route POST https://api.superlabel.ca/api/v1/client/build-route
Full documentation
GQL GraphQL Operations
# Single endpoint POST https://api.superlabel.ca/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
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.superlabel.ca/api/ai-skill -o .claude/skills/superroute-ai-integration.md # Cursor curl -sS https://api.superlabel.ca/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.superlabel.ca/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.superlabel.ca" 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.

Code Examples

REST REST API — Track Package
Track a package (no token required)
curl https://api.superlabel.ca/api/v1/tracking/SR123456
Track a package (no token required)
<?php $res = (new \GuzzleHttp\Client())->get('https://api.superlabel.ca/api/v1/tracking/SR123456'); print_r(json_decode($res->getBody(), true));
Track a package (no token required)
import requests res = requests.get('https://api.superlabel.ca/api/v1/tracking/SR123456') print(res.json())
Track a package (no token required)
resp, _ := http.Get("https://api.superlabel.ca/api/v1/tracking/SR123456") var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result)
Track a package (no token required)
const res = await fetch('https://api.superlabel.ca/api/v1/tracking/SR123456'); const data = await res.json();
Track a package (no token required)
HttpClient client = HttpClient.newHttpClient(); HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://api.superlabel.ca/api/v1/tracking/SR123456")) .build(); HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString()); System.out.println(res.body());
Track a package (no token required)
require 'net/http' puts Net::HTTP.get(URI('https://api.superlabel.ca/api/v1/tracking/SR123456'))
GQL GraphQL — Query Orders
Query orders
curl -X POST https://api.superlabel.ca/api/graphql \ -H "Content-Type: application/json" \ -d '{"query":"query { trackingPublic(trackingNumber: \"SR123456\") { trackingNumber status events { timestamp description } } }"}'
Query orders
$query = 'query { trackingPublic(trackingNumber: "SR123456") { trackingNumber status } }'; $res = (new \GuzzleHttp\Client())->post('https://api.superlabel.ca/api/graphql', [ 'json' => ['query' => $query, 'variables' => []], ]); print_r(json_decode($res->getBody(), true));
Query orders
import requests query = 'query { trackingPublic(trackingNumber: "SR123456") { trackingNumber status } }' res = requests.post('https://api.superlabel.ca/api/graphql', json={'query': query, 'variables': {}}) print(res.json())
Query orders
payload, _ := json.Marshal(map[string]interface{}{ "query": `query { trackingPublic(trackingNumber: "SR123456") { trackingNumber status } }`, "variables": map[string]interface{}{}, }) req, _ := http.NewRequest("POST", "https://api.superlabel.ca/api/graphql", bytes.NewBuffer(payload)) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req)
Query orders
const res = await fetch('https://api.superlabel.ca/api/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query: `query { trackingPublic(trackingNumber: "SR123456") { trackingNumber status } }` }), }); const data = await res.json();
Query orders
String body = "{\"query\":\"query { trackingPublic(trackingNumber: \\\"SR123456\\\") { trackingNumber status } }\"}"; HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://api.superlabel.ca/api/graphql")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body)).build(); HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
Query orders
require 'net/http'; require 'json' uri = URI('https://api.superlabel.ca/api/graphql') req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json') req.body = JSON.dump({ query: 'query { trackingPublic(trackingNumber: "SR123456") { trackingNumber status } }' }) puts Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }.body
MCP MCP — Track a Package
2. Track a package (no token required)
curl -X POST https://api.superlabel.ca/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"track_package","arguments":{"tracking_number":"SR123456"}}}'
2. Track a package (no token required)
$payload = [ 'jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call', 'params' => ['name' => 'track_package', 'arguments' => ['tracking_number' => 'SR123456']], ]; $res = (new \GuzzleHttp\Client())->post('https://api.superlabel.ca/mcp', ['json' => $payload]); print_r(json_decode($res->getBody(), true));
2. Track a package (no token required)
import requests payload = { 'jsonrpc': '2.0', 'id': 1, 'method': 'tools/call', 'params': {'name': 'track_package', 'arguments': {'tracking_number': 'SR123456'}}, } res = requests.post('https://api.superlabel.ca/mcp', json=payload) print(res.json())
2. Track a package (no token required)
payload, _ := json.Marshal(map[string]interface{}{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": map[string]interface{}{ "name": "track_package", "arguments": map[string]interface{}{"tracking_number": "SR123456"}, }, }) req, _ := http.NewRequest("POST", "https://api.superlabel.ca/mcp", bytes.NewBuffer(payload)) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req)
2. Track a package (no token required)
const res = await fetch('https://api.superlabel.ca/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'track_package', arguments: { tracking_number: 'SR123456' } }, }), }); const data = await res.json();
2. Track a package (no token required)
String body = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"track_package\",\"arguments\":{\"tracking_number\":\"SR123456\"}}}"; HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://api.superlabel.ca/mcp")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body)).build(); HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
2. Track a package (no token required)
require 'net/http'; require 'json' uri = URI('https://api.superlabel.ca/mcp') req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json') req.body = JSON.dump({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'track_package', arguments: { tracking_number: 'SR123456' } } }) puts Net::HTTP.start(uri.hostname, uri.port) { |h| h.request(req) }.body
© 2026 Super Label. Home