Developer Docs

PackMesh Public API

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

Try PackMesh-Sample-Apps before building your integration

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.

Open PackMesh-Sample-Apps on GitHubView setup guide & sample code

Interactive reference (Swagger)

Use the hosted Swagger UI to explore request/response schemas and try API calls. The public documentation intentionally omits internal admin endpoints.

Open Swagger UIDownload OpenAPI JSON

Developer onboarding portal

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.

Partner credential creation

Create and rotate API keys tied to a workspace. Authenticate service-to-service requests directly with your API key.

  • Assign scopes like scenarios:read and scenario-runs:write.
  • Download credentials once and store them in a secrets manager.
  • Manage rotations in the developer portal.

API usage guides + quickstart

Follow the quickstart below to create a scenario, run it, and retrieve results. The guides will expand as new endpoints are stabilized.

  • Quickstart is ready today in this page.
  • Portal walkthroughs and in-product tips live in the developer portal.

Authentication & authorization

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
  • 401 Unauthorized — missing or invalid API key.
  • 403 Forbidden — authenticated but does not have access to the target scenario.
  • Note: interactive UI sessions continue to use the standard login flow; partner integrations should use API keys for service-to-service access.

SDKs & Postman collection

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.

  • Visit the developer portal for SDK downloads (TypeScript, Python, C#, Java, C++) and the Postman collection.
  • Use the OpenAPI JSON to generate custom SDKs if you need additional languages.

Quickstart

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>"

Versioning policy

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.

  • Minor, backwards-compatible enhancements land within the same version.
  • Deprecated fields will be documented in Swagger before removal.

Scenario runs

Create a scenario run

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"
}

Check run status

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"
}

Scenario results

Download raw result datasets

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 }
    ]
  }
}

Scenario comparisons

Get standard baseline comparison

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"
  }
}

Reference workflow

Use this workflow to integrate PackMesh end to end: create a scenario, run it, retrieve results, and compare against the standard baseline.

  1. Create a scenario with your inputs and options.
  2. Trigger a run and poll for completion.
  3. Download raw datasets for reporting and reconciliation.
  4. Fetch the standard baseline comparison for KPI deltas.
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}