---
title: "Run the provided Pi harness"
method: POST
path: "/v1/sessions/{id}/agent"
---

# Run the provided Pi harness

`POST /v1/sessions/{id}/agent`

## Request

- Base URL: `https://assemble-vms-api.fly.dev`
- URL: `https://assemble-vms-api.fly.dev/v1/sessions/{id}/agent`
- Auth: HTTP bearer

Run one fresh Pi conversation against this session. Omitting provider and model uses the configured service default; supply both to override it. The service must have credentials for the selected provider. The request reserves the session until it finishes. Streams AgentEvent records as NDJSON. Agent history and events are not persisted for replay. Disconnect requests cancellation; requests have a 15-minute deadline.

## Request body

- RunAgent: Uses the service default model when provider and model are omitted. Supply both fields together to override the default.
  - `message` string, required
  - `provider` string, required
  - `model` string, required

## Response `200`

AgentEvent records; done or error is terminal.

## Other responses

- `default`: Structured API error. HTTP 400 invalid request, 401 authentication, 404 missing resource, 409 conflict, 413 size limit, 429 quota, or 503 unavailable.

---

[API](https://skmtc.dev/assemble/apis/assemble-vms-api.md) - [All operations](https://skmtc.dev/assemble/apis/assemble-vms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/assemble/apis/assemble-vms-api/revisions/93f55a2e3de3?raw)