Loading PackMesh
Setting up the latest highlights and navigation.
Developer Docs
This documentation covers the publicly supported endpoints for scenario runs, results, and comparisons. All endpoints are versioned under the /api/v1prefix and require authenticated access unless noted otherwise.
Recommended first step
Want to move faster? Clone PackMesh-Sample-Apps and run complete sample apps in C++, C#, TypeScript, Python, and Java. It is the quickest way to understand expected request flow, auth wiring, and end-to-end scenario execution.
Use the hosted Swagger UI to explore request/response schemas and try API calls. The public documentation intentionally omits internal admin endpoints.
The developer onboarding portal is the home for partner credentials, API usage guides, and quickstart workflows. It is designed around service-to-service access so partner services can integrate without interactive logins.
Create and rotate API keys tied to a workspace. Authenticate service-to-service requests directly with your API key.
Follow the quickstart below to create a scenario, run it, and retrieve results. The guides will expand as new endpoints are stabilized.
Service-to-service credentials are the preferred authentication mechanism for public integrations. Send an API key directly using X-Api-Key or Authorization: ApiKey <key>. Requests from users or services without access to the scenario or workspace will return 403 Forbidden.
GET /api/v1/scenarios X-Api-Key: pmk_live_0f1e2d3c.abc123
Authorization: ApiKey pmk_live_0f1e2d3c.abc123
Download starter SDKs and a curated Postman collection from the developer portal, or generate your own client from the public OpenAPI spec once your integration is stable. For complete end-to-end examples, start with PackMesh-Sample-Apps.
Follow this end-to-end flow using a direct API key. The workflow aligns to the public scenario endpoints available today.
# 1) Create a scenario
curl -X POST -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" -H "Content-Type: application/json" -d '{"name":"Q4 baseline","decisionType":"baseline","status":"draft"}' https://api.packmesh.com/api/v1/scenarios# 2) Run the scenario curl -X POST -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" -H "Content-Type: application/json" -H "Idempotency-Key: <uuid>" https://api.packmesh.com/api/v1/scenarios/<scenarioId>/runs
# 3) Fetch results curl -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" "https://api.packmesh.com/api/v1/scenarios/<scenarioId>/results/raw?dataset=packaging&runId=<runId>"
PackMesh uses URL-based versioning. All public endpoints live under/api/v1. Breaking changes will be released as/api/v2 with at least six months of overlap and deprecation notices in advance.
Starts a run for the specified scenario. Returns a run identifier immediately.
Auth: API key required; caller must belong to the scenario workspace.
POST /api/v1/scenarios/{scenarioId}/runs
# Example
curl -X POST -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" -H "Idempotency-Key: <uuid>" https://api.packmesh.com/api/v1/scenarios/2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9/runs{
"runId": "run_2024_09_15_001"
}Poll the run status to track progress or identify failures.
Auth: API key required; caller must belong to the scenario workspace.
GET /api/v1/scenarios/{scenarioId}/runs/{runId}
# Example
curl -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" https://api.packmesh.com/api/v1/scenarios/2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9/runs/run_2024_09_15_001{
"runId": "run_2024_09_15_001",
"scenarioId": "2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9",
"status": "Running",
"progressStep": "packaging",
"progressPercent": 42.5,
"lastUpdatedAt": "2024-09-15T14:28:12Z"
}Retrieve raw export datasets for a completed run. Common datasets includepackaging,pallets,shipments, andunplaced.
Auth: API key required; caller must belong to the scenario workspace.
GET /api/v1/scenarios/{scenarioId}/results/raw?dataset=packaging&runId={runId}
# Example
curl -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" "https://api.packmesh.com/api/v1/scenarios/2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9/results/raw?dataset=packaging&runId=run_2024_09_15_001"{
"scenarioId": "2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9",
"runId": "run_2024_09_15_001",
"dataset": "packaging",
"data": {
"columns": [
{ "key": "sku", "label": "SKU" },
{ "key": "box_type", "label": "Box" },
{ "key": "quantity", "label": "Quantity" }
],
"rows": [
{ "sku": "BX-100", "box_type": "Small", "quantity": 120 },
{ "sku": "BX-200", "box_type": "Medium", "quantity": 56 }
]
}
}Baselines compare a run to standardized assumptions. Use this endpoint to fetch the baseline results and provenance data used in comparisons and KPI deltas.
Auth: API key required; caller must belong to the scenario workspace.
GET /api/v1/scenarios/{scenarioId}/baseline/standard?runId={runId}
# Example
curl -H "X-Api-Key: pmk_live_0f1e2d3c.abc123" "https://api.packmesh.com/api/v1/scenarios/2a09f9f3-0e2c-4a49-b52b-1f71bfa2b0d9/baseline/standard?runId=run_2024_09_15_001"{
"results": {
"solutionId": "baseline_2024_09",
"summary": "Standard baseline for September 2024",
"metrics": {
"totalCostUsd": 12500.42,
"totalCo2Kg": 842.3,
"palletCount": 32,
"shipmentCount": 14
},
"recommendedOptions": {
"allowSplitShipments": true,
"optimizeFor": "cost"
},
"assumptions": ["Standard shipping network", "Average lane distances"],
"dataQuality": {
"missingWeightsPct": 0,
"missingDimsPct": 1.2
},
"generatedAt": "2024-09-15T14:32:01Z",
"insights": {
"highlights": ["Baseline uses standard LTL consolidation."],
"warnings": []
},
"warnings": []
},
"provenance": {
"sourceRunId": "run_2024_09_15_001",
"dateRangeStart": "2024-08-01",
"dateRangeEnd": "2024-08-31",
"dataVersion": "2024.09"
}
}Use this workflow to integrate PackMesh end to end: create a scenario, run it, retrieve results, and compare against the standard baseline.
GET /api/v1/scenarios/{scenarioId}/runs/{runId}
GET /api/v1/scenarios/{scenarioId}/results/raw?dataset=packaging&runId={runId}
GET /api/v1/scenarios/{scenarioId}/baseline/standard?runId={runId}