# Factory Steer

Source: https://opvs.ai/docs/api/factory-steer

## `POST` /api/v1/factory/steer/builds/{task_ref}/tell

**Tell Running Build**

Tell a card's running build, or durably park the message on the card.

**Parameters**

- `task_ref` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/tell' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/tell",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"message": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/tell", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"message": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"message": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/tell", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/factory/steer/builds/{task_ref}/read

**Read Running Build**

Read a card's live command/steps and its recent planner messages.

**Parameters**

- `task_ref` (path, string, required)
- `last` (query, integer, optional)
- `format` (query, string, optional)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/read' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/read",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/read", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/read", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/factory/steer/sessions

**List Fleet Live Sessions**

What every machine in the brand is running RIGHT NOW, in one call.

**Parameters**

- `env_ids` (query, any, optional) — Comma-separated env ids (canonical UUID or `env_…` short code). Omit for every machine in the brand.
- `timeout` (query, any, optional) — Per-box budget in seconds (clamped 1–30, default 6)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/factory/steer/sessions' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/factory/steer/sessions",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/sessions", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/factory/steer/sessions", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/factory/steer/environments/{env_id}/sessions

**List Live Sessions**

List the sessions running live on an env — the steer-target picker.

**Parameters**

- `env_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/factory/steer/boards/{board_id}/sessions

**List Board Live Sessions**

List the LIVE sessions across EVERY env serving a factory board — the board-scoped steer-target picker.

**Parameters**

- `board_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/factory/steer/boards/{board_id}/sessions' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/factory/steer/boards/{board_id}/sessions",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/boards/{board_id}/sessions", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/factory/steer/boards/{board_id}/sessions", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause

**Pause Session**

Freeze a running session mid-turn (brand admin only).

**Parameters**

- `env_id` (path, string, required)
- `session_id` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume

**Resume Session**

Thaw a paused session (brand admin only) — it continues from where it stopped (``SIGCONT`` on the group). No-op if the session isn't paused.

**Parameters**

- `env_id` (path, string, required)
- `session_id` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject

**Inject Session**

Queue a steer message for a running session (brand admin only).

**Parameters**

- `env_id` (path, string, required)
- `session_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"message": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"message": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"message": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## Tell Running Build

`POST https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/tell`

Also as: MCP `tool_call software-factory.tellRunningBuild` · skill `software-factory`

Tell a card's running build, or durably park the message on the card.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read Running Build

`GET https://app.opvs.ai/api/v1/factory/steer/builds/{task_ref}/read`

Also as: MCP `tool_call software-factory.readRunningBuild` · skill `software-factory`

Read a card's live command/steps and its recent planner messages.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Fleet Live Sessions

`GET https://app.opvs.ai/api/v1/factory/steer/sessions`

Also as: MCP `tool_call software-factory.listFleetLiveSessions` · skill `software-factory`

What every machine in the brand is running RIGHT NOW, in one call.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Live Sessions

`GET https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions`

Also as: MCP `tool_call software-factory.listDeskLiveSessions` · skill `software-factory`

List the sessions running live on an env — the steer-target picker.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Board Live Sessions

`GET https://app.opvs.ai/api/v1/factory/steer/boards/{board_id}/sessions`

Also as: MCP `tool_call software-factory.listBoardLiveSessions` · skill `software-factory`

List the LIVE sessions across EVERY env serving a factory board — the
board-scoped steer-target picker.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Pause Session

`POST https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/pause`

Also as: MCP `tool_call software-factory.pauseLiveSession` · skill `software-factory`

Freeze a running session mid-turn (brand admin only).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Resume Session

`POST https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/resume`

Also as: MCP `tool_call software-factory.resumeLiveSession` · skill `software-factory`

Thaw a paused session (brand admin only) — it continues from where it
stopped (``SIGCONT`` on the group). No-op if the session isn't paused.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Inject Session

`POST https://app.opvs.ai/api/v1/factory/steer/environments/{env_id}/sessions/{session_id}/inject`

Also as: MCP `tool_call software-factory.injectLiveSession` · skill `software-factory`

Queue a steer message for a running session (brand admin only).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |