# POST /path

> Talos 0.7 · Since 0.6

## Request

#### Request body: `PathRequest`

`POST /path` request.

| Field | Type | Required | Description |
|---|---|---|---|
| `from` | `number[3]` | yes | Start position in world space. |
| `to` | `number[3]` | yes | Goal position in world space. |

## Response

#### Response: `PathResult`

The full result of a path query.

| Field | Type | Present | Description |
|---|---|---|---|
| `status` | `PathStatus` | always | How the query ended. |
| `waypoints` | `number[3][]` | always | Waypoints from `from` to as far as the query got, start and goal included. Empty when the status is `start_off_mesh`, `goal_off_mesh`, or `failed`. |
| `length` | `number` | always | Summed length of the waypoint run, in metres. |
| `frame` | `integer` | always | The frame the query ran on. |
| `links` | `PathLinkView[]` | sometimes | Every off-mesh link the waypoints cross, in path order. Omitted when the route walks the whole way. |

#### Response: `PathLinkView`

One link a path crosses: from `waypoints[waypoint]` to `waypoints[waypoint + 1]`.

| Field | Type | Present | Description |
|---|---|---|---|
| `waypoint` | `integer` | always | Index of the waypoint where the crossing starts. |
| `link` | `integer` | always | Index into `GET /navmesh`'s `links`. |
| `kind` | `NavLinkKindView` | always | What crossing it takes. |
| `action` | `string` | sometimes | What to press at the start. Absent: just move. |
| `hold` | `number` | sometimes | Seconds to hold `action` down. Absent when there is no action. |
| `entity` | `string` | sometimes | The declaring entity; absent for a generated link. |

#### Response: `NavLinkKindView`

What crossing a link takes. Mirrors `argus_nav::NavLinkKind`.

| Value | Meaning |
|---|---|
| `jump` | Jump from the start to the end. |
| `drop` | Walk off the start and fall to the end. |
| `generic` | Anything else; `action` says what to do. |

#### Response: `PathStatus`

Why a path query ended the way it did. Mirrors `argus_nav::PathOutcome`.

| Value | Meaning |
|---|---|
| `complete` | The waypoints reach the goal. |
| `partial` | The waypoints run as far as the navmesh allows, but stop short of the goal. |
| `start_off_mesh` | `from` is not on the navmesh. |
| `goal_off_mesh` | `to` is not on the navmesh. |
| `failed` | Both ends are on the mesh but no corridor connects them. |

## Example

```sh
curl -X POST "http://127.0.0.1:7700/path" --json @body.json
```

Start a server with `argus run --serve`; the port is `--port` (7700 by default). The request and response fields are in the query API guide.