---
title: "Chat with a running runtime agent"
method: POST
path: "/v1/runtimes/{runtimeId}/chat"
tags: ["Runtimes"]
---

# Chat with a running runtime agent

`POST /v1/runtimes/{runtimeId}/chat`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/runtimes/{runtimeId}/chat`
- Auth: HTTP bearer

Human-only. Proxies to the runtime container's OpenAI-compatible
`POST /v1/chat/completions` (hermes / openclaw / openclaude / opencode chat bridge).
Starts the runtime if stopped. Streams SSE when `Accept: text/event-stream`
or `stream: true`. Conversation history is ephemeral (pass `messages`).
Requires a public URL (shell access, Shroud sidecar, or HTTP hosting).

## Path parameters

- `runtimeId` string, uuid, required

## Request body

- RuntimeChatRequest: Chat with the agent inside a runtime. Provide `message` and/or a full OpenAI-style `messages` array (ephemeral history).
  - `message` string: Latest user message
  - `messages` object[]: OpenAI chat messages (optional history)
  - `model` string
  - `provider` string
  - `stream` boolean: Request SSE streaming (default true when Accept is text/event-stream)

## Response `200`

Chat completion (JSON) or SSE stream

- object

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid
- `403`: Insufficient permissions
- `404`: Resource not found
- `503`: The runtime's last start failed less than 120 seconds ago and is not being retried yet. Chat starts a stopped runtime, so a client that retries on failure turns every attempt into another deploy — one polling client did exactly that every 8 seconds for days. Wait out the cooldown, or call the start endpoint to see the underlying error.

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)