---
title: "Request a device action"
method: POST
path: "/v1/conversations/{id}/device-requests"
tags: ["Conversations"]
---

# Request a device action

`POST /v1/conversations/{id}/device-requests`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/conversations/{id}/device-requests`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Request body

- object
  - `kind` 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally' | 'dir_list' | 'project_link', required
  - `device_id` string: Send it to this computer of yours (the `device_id` of its heartbeats) and no other.
  - `device` string: Send it to this computer of yours, by its device id or its name (GET /v1/devices; any case), and no other. Without `device` or `device_id`: the computer the conversation is linked to, then one with the project, then the one used last; when that is unclear the person picks it (a needs-you item).
  - `exec` object
    - `argv` string[], required
    - `cwd_relative` string
    - `timeout_seconds` integer
  - `files` object
    - `local_path_relative` string, required: Relative to the conversation’s folder on the device, or absolute or `~/…` for a file elsewhere on it.
    - `remote_path` string, required
    - `max_bytes` integer, required
  - `port` object
    - `remote_port` integer, required
    - `local_port` integer, required
  - `dir` object: `dir_list`: the names, kinds, sizes and Git remotes in a folder on the device, never file contents.
    - `path` string, required: A folder on the device: absolute, or `~/…` for its home folder.
    - `depth` integer: Levels below `path` to list. Default 1.
    - `max_entries` integer: At most this many entries. Default 500.
    - `include_hidden` boolean: Include names that start with a dot. Default false.
  - `link` object: `project_link`: the folder becomes one of your projects, seeded from the device (uncommitted files too, .gitignore respected).
    - `path` string, required: A folder on the device: absolute, or `~/…` for its home folder.
    - `brief` string: Also start a conversation in that folder with this first prompt.
    - `harness` 'claude' | 'codex'

## Response `202`

Default Response

- object
  - `request` object, required
    - `kind` 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally' | 'dir_list' | 'project_link', required
    - `device_id` string, nullable, required
    - `device` string: Send it to this computer of yours, by its device id or its name (GET /v1/devices; any case), and no other. Without `device` or `device_id`: the computer the conversation is linked to, then one with the project, then the one used last; when that is unclear the person picks it (a needs-you item).
    - `exec` object
      - `argv` string[], required
      - `cwd_relative` string
      - `timeout_seconds` integer
    - `files` object
      - `local_path_relative` string, required: Relative to the conversation’s folder on the device, or absolute or `~/…` for a file elsewhere on it.
      - `remote_path` string, required
      - `max_bytes` integer, required
    - `port` object
      - `remote_port` integer, required
      - `local_port` integer, required
    - `dir` object: `dir_list`: the names, kinds, sizes and Git remotes in a folder on the device, never file contents.
      - `path` string, required: A folder on the device: absolute, or `~/…` for its home folder.
      - `depth` integer: Levels below `path` to list. Default 1.
      - `max_entries` integer: At most this many entries. Default 500.
      - `include_hidden` boolean: Include names that start with a dot. Default false.
    - `link` object: `project_link`: the folder becomes one of your projects, seeded from the device (uncommitted files too, .gitignore respected).
      - `path` string, required: A folder on the device: absolute, or `~/…` for its home folder.
      - `brief` string: Also start a conversation in that folder with this first prompt.
      - `harness` 'claude' | 'codex'
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `conversation_id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `state` 'pending' | 'approved' | 'denied' | 'running' | 'done' | 'failed' | 'device_unavailable', required
    - `retryable` boolean, required
    - `result` object, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

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