---
title: "Run shell command"
method: POST
path: "/session/{sessionID}/shell"
---

# Run shell command

`POST /session/{sessionID}/shell`

Execute a shell command within the session context and return the AI's response.

## Path parameters

- `sessionID` string, required

## Query parameters

- `directory` string

## Request body

- object
  - `agent` string, required
  - `model` object
    - `providerID` string, required
    - `modelID` string, required
  - `command` string, required

## Response `200`

Created message

- AssistantMessage
  - `id` string, required
  - `sessionID` string, required
  - `role` 'assistant', required
  - `time` object, required
    - `created` number, required
    - `completed` number
  - `error` union
    - ProviderAuthError
      - `name` 'ProviderAuthError', required
      - `data` object, required
        - `providerID` string, required
        - `message` string, required
    - UnknownError
      - `name` 'UnknownError', required
      - `data` object, required
        - `message` string, required
    - MessageOutputLengthError
      - `name` 'MessageOutputLengthError', required
      - `data` object, required
    - MessageAbortedError
      - `name` 'MessageAbortedError', required
      - `data` object, required
        - `message` string, required
    - APIError
      - `name` 'APIError', required
      - `data` object, required
        - `message` string, required
        - `statusCode` number
        - `isRetryable` boolean, required
        - `responseHeaders` object
        - `responseBody` string
        - `metadata` object
  - `parentID` string, required
  - `modelID` string, required
  - `providerID` string, required
  - `mode` string, required
  - `agent` string, required
  - `path` object, required
    - `cwd` string, required
    - `root` string, required
  - `summary` boolean
  - `cost` number, required
  - `tokens` object, required
    - `input` number, required
    - `output` number, required
    - `reasoning` number, required
    - `cache` object, required
      - `read` number, required
      - `write` number, required
  - `finish` string

## Other responses

- `400` — Bad request
- `404` — Not found

## Changes

> 50 revisions in range; 1 could not be searched.

- **2026-02-14** `9df3a7d5f839` — 3 warning, 1 info
  - removed the optional property `structured` from the response with the `200` status
  - removed the optional property `tokens/total` from the response with the `200` status
  - removed the optional property `variant` from the response with the `200` status
  - removed `#/components/schemas/StructuredOutputError, #/components/schemas/ContextOverflowError` from the `error` response property `anyOf` list for the response status `200`
- **2026-02-12** `7eb1c31fb938` — 2 info
  - added the optional property `structured` to the response with the `200` status
  - added `#/components/schemas/StructuredOutputError` to the `error` response property `anyOf` list for the response status `200`
- **2026-02-11** `8f23f1074f57` — 1 info
  - added the optional property `tokens/total` to the response with the `200` status
- **2026-02-09** `3e70f65f33fa` — 1 info
  - added `#/components/schemas/ContextOverflowError` to the `error` response property `anyOf` list for the response status `200`
- **2026-02-06** `73bbed0ce3ce` — 1 info
  - added the optional property `variant` to the response with the `200` status

[Change history](https://skmtc.dev/martian-engineering/apis/voltcode/changes/session/:sessionID/shell/post.md)

---

[API](https://skmtc.dev/martian-engineering/apis/voltcode.md) · [All operations](https://skmtc.dev/martian-engineering/apis/voltcode/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/martian-engineering/voltcode/revisions/d28625e4a7ea/schema)