> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solve

> Plan vehicle routes, assign items to options, pack items within capacity limits or schedule jobs on resources, returning constraint checks and conflicts.

**Routing, allocation, packing and scheduling are supported.**

## Quote and job lifecycle

The first request returns HTTP 402 with a [quoted price](/pricing#solve). Retry identical input with `X-Quote-ID`, payment and an `Idempotency-Key`; HTTP 202 returns a `request_id` to poll at `GET /v1/requests/:id`. Same key and input return the original job.

SDKs (`agent.solve`, `client.solve`/`asolve`) handle quoting, payment and polling (420-second timeout); MCP, LangChain and GAME expose `oneshot_solve`, GAME with JSON-text blocks.

## Routing

Minimise distance, time, or vehicles then distance over vehicles, stops and coordinates or `ids`-ordered square matrices. Optional demand, service times, windows and shifts constrain routes; every stop is served. Defaults: kilometres, minutes, 40 units/hour.

Input:

```json theme={null}
{
  "problem": "routing",
  "time_limit_s": 30,
  "routing": {
    "objective": "distance",
    "vehicles": [{ "id": "van", "capacity": 10, "start": { "id": "depot" } }],
    "stops": [{ "id": "delivery", "demand": 1, "location": { "id": "delivery" } }],
    "matrix": {
      "ids": ["depot", "delivery"],
      "distance": [[0, 1], [1, 0]],
      "time": [[0, 1], [1, 0]]
    }
  }
}
```

Example result:

```json theme={null}
{
  "status": "feasible",
  "objective_value": 2,
  "bound": null,
  "gap": null,
  "solution": {
    "routes": [{
      "vehicle": "van",
      "stops": [{ "id": "delivery", "arrival": 1, "departure": 1, "load_after": 1 }],
      "distance": 2,
      "time": 2
    }],
    "unserved": []
  },
  "checks": [
    { "name": "every_stop_once", "satisfied": true, "worst_violation": 0, "detail": "" },
    { "name": "vehicle_capacity", "satisfied": true, "worst_violation": 0, "detail": "" },
    { "name": "stop_windows", "satisfied": true, "worst_violation": 0, "detail": "" },
    { "name": "shift_windows", "satisfied": true, "worst_violation": 0, "detail": "" },
    { "name": "route_continuity", "satisfied": true, "worst_violation": 0, "detail": "" },
    { "name": "objective", "satisfied": true, "worst_violation": 0, "detail": "" }
  ],
  "conflicts": [],
  "meta": {
    "problem": "routing",
    "size": { "stops": 1, "vehicles": 1 },
    "variables_estimated": 12,
    "variables_built": 12,
    "solve_time_s": 0.1,
    "time_limit_s": 30,
    "conflicts_complete": null
  }
}
```

## Allocation

Assign `items` (`quantity` default 1) to `options` (optional `capacity`) using `pairs` (per-unit `cost`/`value`). Optional: `split`, `max_total_cost`, `min_share`/`max_share` (`if_used` floors), `required`, `forbidden`. `maximise_value` may leave items `unassigned`; with shares or a budget, largest/smallest lot ratio ≤1,000,000 (`bad_quantity` before payment).

```json theme={null}
{
  "problem": "allocation",
  "allocation": {
    "objective": "minimise_cost",
    "items": [{ "id": "L1", "quantity": 120 }, { "id": "L2", "quantity": 80 }, { "id": "L3", "quantity": 100 }],
    "options": [{ "id": "C1", "capacity": 200 }, { "id": "C2", "capacity": 150 }],
    "pairs": [
      { "item": "L1", "option": "C1", "cost": 1.9 }, { "item": "L1", "option": "C2", "cost": 2.1 },
      { "item": "L2", "option": "C1", "cost": 2.4 }, { "item": "L2", "option": "C2", "cost": 2.0 },
      { "item": "L3", "option": "C1", "cost": 1.7 }
    ],
    "min_share": [{ "option": "C2", "share": 0.25 }]
  }
}
```

## Packing

Size/capacity keys match `dimensions`. Quantities: default 1, maximum 1,000,000. `bin` minimises bins; `knapsack` maximises nonnegative `value`s using one bin. `incompatible` pairs forbid sharing; equal IDs return `contradictory_input` before quoting. No geometric placement.

```json theme={null}
{
  "problem": "packing",
  "packing": {
    "variant": "bin",
    "dimensions": ["weight"],
    "bins": [{ "id": "box", "capacity": { "weight": 10 }, "quantity": 3 }],
    "items": [
      { "id": "A", "size": { "weight": 5 }, "quantity": 2 },
      { "id": "B", "size": { "weight": 4 }, "quantity": 2 },
      { "id": "C", "size": { "weight": 1 }, "quantity": 2 }
    ]
  }
}
```

Result: two bins, `status: "optimal"`, `gap: 0`; a knapsack solution adds `left_out: [{id,count}]`:

```json theme={null}
{
  "bins": [
    { "bin": "box", "index": 0, "items": [{ "id": "A", "count": 2 }], "used": { "weight": 10 } },
    { "bin": "box", "index": 1, "items": [{ "id": "B", "count": 2 }, { "id": "C", "count": 2 }], "used": { "weight": 10 } }
  ]
}
```

## Schedule

Jobs carry integer `duration`, optional `release`, `due`, per-resource `needs` and `weight`; resources carry `capacity`, optional `calendar` windows and `cost_per_unit_time`; `precedence` makes `after` start `lag` after `before` ends. Times are integers in `time_unit` (default minutes); jobs fit one calendar window. Objectives: `makespan`; `tardiness` (weighted lateness past `due`, else a hard deadline); `cost` (`weight` × `duration` × held needs at their rate).

Input and solution:

```json theme={null}
{"problem":"schedule","schedule":{"objective":"makespan","resources":[{"id":"machines","capacity":2}],"jobs":[{"id":"job","duration":10,"needs":{"machines":1}}]}}
```

```json theme={null}
{"starts":[{"job":"job","start":0,"end":10,"resources":{"machines":1},"tardiness":0}],"makespan":10}
```

## Status, checks and conflicts

| Result status | Meaning |
| - | - |
| `optimal` | Proven optimum; never for routing. |
| `feasible` | Checked solution without proven optimality. |
| `infeasible` | Proven contradiction; solution/objective/bound/gap null, checks empty. |
| `timeout` | Time elapsed; may carry a checked solution; charged regardless. |

Every field is present; routing bound/gap are null. Objectives are recomputed independently; without a solution, objective null, checks empty.

`checks[]` (`name`, `satisfied`, `worst_violation` in input units, `detail`) all pass, or the job fails with `internal_error`.

`conflicts[]` (infeasible only): `constraints[]` (`family`, `ref`, `label`) plus `explanation`, not necessarily minimal; `meta.conflicts_complete` reports completeness.

## Limits

500 stops; integer `time_limit_s` 1–300, default 30; quantities finite, nonnegative, at most 1e12; at most 100,000 estimated variables:

```text theme={null}
routing:    4 * (stops + 2 * vehicles)
allocation: 2 * pairs + options + items
packing:    bins * (item kinds + 1)    for bin;  item kinds    for knapsack
schedule:   jobs * (3 + resources) + precedence + calendar windows + horizon
```

Pricing size: allocation items × options; packing kinds × bins × dimensions; else the estimate. Unsupported numeric precision/magnitudes fail before payment.

Unknown fields, duplicate/empty/unknown IDs, reversed/overlapping windows, malformed matrices, contradictory pairs and precedence cycles fail before payment: HTTP 400, `error: "invalid_input"`, named `code` and `message`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.