# POST /raycast

> Talos 0.6 · Since 0.6

One ray `{ from, dir, … }`, or several under `{ "rays": [...] }`.

The body is read as JSON first and matched here rather than by `Body`, so a body of neither shape is told what the endpoint takes (`RAYCAST_BODY`) and not only which field was missing.

## Request

#### Body fields

| field | default | Notes |
|---|---|---|
| `exclude` | none | an entity id, or a list of them, the ray passes straight through. An id the scene does not have is a `404` |
| `exclude_tags` | none | a tag, or a list; every entity carrying one is passed through too |
| `triggers` | `true` | whether trigger volumes count as hits, as `ctx.world.raycast` has it |

#### Request body: `RaycastRequest`

`POST /raycast` request: one ray.

| Field | Type | Required | Description |
|---|---|---|---|
| `from` | `number[3]` | yes | Ray origin in world space, `[x, y, z]`. `origin` is accepted for it: agents guessed `{ origin, direction, maxDistance }` three runs in a row and were refused each time. |
| `dir` | `number[3]` | yes | Ray direction. Need not be normalized, but must not be the zero vector. `direction` is accepted for it. |
| `max` | `number` | no | Maximum distance in metres. Defaults to 1000. `maxDistance` and `max_distance` are accepted for it. |
| `exclude` | `string[]` | no | Entity ids the ray passes straight through: an id or a list of them. A ray cast down from above the player starts outside its capsule and hits it first; `"exclude": "player"` sees past it. An id the scene does not have is a `404`, so a typo is not a silent no-op. |
| `exclude_tags` | `string[]` | no | Every entity carrying any of these tags is passed through as well: a tag or a list. `excludeTags`, as `ctx.world.raycast` spells it, is accepted for it. |
| `triggers` | `boolean` | no | Whether trigger volumes count as hits. Default `true`, as `ctx.world.raycast` has it; pass `false` for a line of sight or a ground probe that should see through a volume. |

#### Request body: `RaycastBatch`

`POST /raycast` with `{ "rays": [ … ] }`: several rays, cast on one frame, answered in order.

| Field | Type | Required | Description |
|---|---|---|---|
| `rays` | `RaycastRequest[]` | yes | The rays, each the single-ray body. |

## Response

#### Response: `HitView`

What a ray found. `POST /raycast` responds with this or with `null`.

| Field | Type | Present | Description |
|---|---|---|---|
| `entity` | `string` | always | The entity the ray struck, by id. |
| `point` | `number[3]` | always | World-space point of impact. |
| `normal` | `number[3]` | always | Surface normal at the impact point. |
| `distance` | `number` | always | Distance from `from` along the normalized direction, in metres. |
| `frame` | `integer` | always | The frame the cast ran on. |

## Example

```sh
curl -X POST "http://127.0.0.1:7700/raycast" --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.