# Jumpers

Source: https://docs.arcweave.com/rest-api/jumpers
Section: REST API
Description: REST API endpoints for jumpers

Jumper endpoints create, retrieve, update, and delete jumpers that point to project elements.

## Endpoints

Context: Arcweave docs > REST API > Jumpers > Endpoints

### Create jumper

Context: Arcweave docs > REST API > Jumpers > Endpoints > Create jumper

`POST /api/v1/{hash}/jumper`

**Request**

```http title="HTTP"
POST /api/v1/{hash}/jumper
```

```bash title="curl"
curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/jumper"
```

```json
{
  "boardId": "b1",
  "x": 450,
  "y": 650.5,
  "elementId": "e1"
}
```

| Property    | Required | Type             | Description                                                                     |
| ----------- | -------- | ---------------- | ------------------------------------------------------------------------------- |
| `boardId`   | Yes      | String           | Board that will contain the jumper.                                             |
| `x`         | Yes      | Number           | Horizontal board coordinate.                                                    |
| `y`         | Yes      | Number           | Vertical board coordinate.                                                      |
| `width`     | No       | Number           | Jumper width. Defaults to `185`.                                                |
| `height`    | No       | Number           | Jumper height. Defaults to `86`.                                                |
| `elementId` | No       | String or `null` | Target element. Defaults to `null`; a string must identify an existing element. |

The jumper must fit inside the `40000` by `40000` board canvas. `width` and `height` must each be between `0` and `40000`; `x` must be between `0` and `40000 - width`, and `y` must be between `0` and `40000 - height`.

`boardId` must identify a regular board, not a folder. The target element can be on any board. If the target element is deleted, the jumper remains and its `elementId` becomes `null`.

The server generates the jumper ID.

**Response**

Returns `201 Created` with the generated resource ID and project version data:

```json
{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"],
  "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c"
}
```

### Get jumper

Context: Arcweave docs > REST API > Jumpers > Endpoints > Get jumper

`GET /api/v1/{hash}/jumper/{jumperID}`

**Request**

```http title="HTTP"
GET /api/v1/{hash}/jumper/{jumperID}
```

```bash title="curl"
curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}"
```

**Response**

Returns `200 OK`.

```json
{
  "id": "jump1",
  "boardId": "b1",
  "x": 900,
  "y": 15000,
  "elementId": "e1"
}
```

### Update jumper

Context: Arcweave docs > REST API > Jumpers > Endpoints > Update jumper

`PATCH /api/v1/{hash}/jumper/{jumperID}`

**Request**

```http title="HTTP"
PATCH /api/v1/{hash}/jumper/{jumperID}
```

```bash title="curl"
curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}"
```

```json
{
  "x": 500.25,
  "elementId": "e4"
}
```

| Property    | Required | Type             | Description                                             |
| ----------- | -------- | ---------------- | ------------------------------------------------------- |
| `x`         | No       | Number           | Updated horizontal coordinate.                          |
| `y`         | No       | Number           | Updated vertical coordinate.                            |
| `width`     | No       | Number           | Updated width.                                          |
| `height`    | No       | Number           | Updated height.                                         |
| `elementId` | No       | String or `null` | Updated target element. Use `null` to clear the target. |

Geometry updates must keep the complete jumper inside the `40000` by `40000` board canvas. The server uses the jumper's current geometry for fields omitted from the request.

The request must contain at least one supported field.

**Response**

Returns `200 OK` with project version data:

```json
{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}
```

### Delete jumper

Context: Arcweave docs > REST API > Jumpers > Endpoints > Delete jumper

`DELETE /api/v1/{hash}/jumper/{jumperID}`

**Request**

```http title="HTTP"
DELETE /api/v1/{hash}/jumper/{jumperID}
```

```bash title="curl"
curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/jumper/{jumperID}"
```

Deleting a jumper also deletes connections that target it.

**Response**

Returns `200 OK` with project version data:

```json
{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}
```

## Common errors

Context: Arcweave docs > REST API > Jumpers > Common errors

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| `400`  | Invalid payload, unsupported field, invalid numeric value, or `boardId` identifies a folder. |
| `403`  | Project permission denied.                                                                   |
| `404`  | Project or jumper not found when retrieving a jumper.                                        |
| `409`  | The board, jumper, or target element does not exist when the command is applied.             |