---
search:
  tags:
    - Agent
    - POST
seo:
  description: >-
    Requires action scope for OAuth callers and a current per-device… Reference
    for the POST /v1/devices/{deviceId}/actions endpoint in the openlaunch API.
sidebar:
  label: Request device action
  badge: POST
title: Request device action
type: openapi-operation
---
Requires action scope for OAuth callers and a current per-device capability grant. Idempotency key is 1–128 characters; TTL defaults to 30 seconds and is at most 300 seconds. Duplicate retries with the same key and identical request return the existing receipt; key reuse with a different request conflicts. Physical execution is not exactly once.

`POST /v1/devices/{deviceId}/actions`

**ol CLI**

```bash
ol call "$DEVICE_ID" device.health '{}' --key health-001
```

**openlaunch SDK**

```ts
import { createClient } from "@openlaunch/sdk";
const agent = createClient({ url: process.env.OPENLAUNCH_URL ?? "https://www.openlaunch.dev", token: process.env.OPENLAUNCH_AGENT_TOKEN! });
const receipt = await agent.requestAction(deviceId, { capability: "device.health", arguments: {}, idempotencyKey: "health-001" });
```