# POST /entity/{id}/teleport

> Talos next · Since 0.6

Move one entity outright: the same path as a behaviour's `ctx.entity.teleport`, answered after the move is published.

## Request

#### Request body: `TeleportRequest`

`POST /entity/{id}/teleport` request: put the entity somewhere else outright.

| Field | Type | Required | Description |
|---|---|---|---|
| `position` | `number[3]` | yes | Where to, `[x, y, z]`: the entity's own position, local to its parent if it has one. |
| `yaw` | `number` | no | Heading in radians about +Y, 0 facing -Z. Absent: the facing is left alone. |

## Response

#### Response: `TeleportResponse`

`POST /entity/{id}/teleport` response.

| Field | Type | Present | Description |
|---|---|---|---|
| `entity` | `string` | always | The entity moved. |
| `position` | `number[3]` | always | Where it landed. A character put inside geometry is pushed out of it, so this can differ from the position asked for. |
| `frame` | `integer` | always | The frame the move is part of: a read at this frame or later sees it. |

#### Response: `EventRecord`

One frame-stamped thing that happened.

| Field | Type | Present | Description |
|---|---|---|---|
| `seq` | `integer` | always | Monotonic per-process sequence number. Strictly increasing, no gaps. |
| `frame` | `integer` | always | The frame the event fired on. |
| `time` | `number` | always | Simulated seconds since the scene loaded. |
| `kind` | `EventKind` | always | What happened. |

#### Response: `EventKind`

The payload of an `EventRecord`, tagged by `type` on the wire.

| Value | Meaning |
|---|---|
| `collision` | Two colliders started or stopped touching. Mirrors `argus_host::GameEvent::Collision`. |
| `trigger` | A sensor volume was entered or left. Mirrors `argus_host::GameEvent::Trigger`. |
| `custom` | `ctx.events.emit(name, data)` from a behavior, or `ctx.events.emitTo(to, name, data)`. |
| `script_error` | A behavior threw, ran away or blew its per-tick budget and was disabled — or, with `disabled` false, keeps running: it threw a stale handle (`entity-despawned`) from a per-tick hook, or its `update` stayed over its wall-clock budget (phase `budget`) under the host's default `OverrunPolicy::Warn`. |
| `script_warning` | A behavior did something the engine let pass but its author almost certainly did not mean. The behavior keeps running; nothing is disabled. |
| `ui` | The game UI's stack, focus or an activation changed (`PLAN-UI.md` §3). |
| `log` | `ctx.log(...)` from a behavior. |

## Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | Taken from the path: `id`. |

## Example

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