Request action on multiple devices

Up to 20 devices. Per-device authorization and schema checks apply. Results are independent; broadcast is not atomic. TTL defaults to 30 seconds and is at most 300 seconds.

POST/v1/broadcasts

Authorization

AuthorizationBearer token (Clerk owner session) · headerrequired

Owner identity required.

AuthorizationBearer token (ol_agent token) · headerrequired

Owner-issued agent API connection; access ceiling and live device grants are checked separately.

AuthorizationBearer token (OAuth access token) · headerrequired

OAuth read/act scope is a ceiling. Scopes do not create device grants.

Request body

requiredapplication/json

deviceIdsstring<uuid>[]required

min items 1 · max items 20

capabilitystringrequired

min length 1 · max length 64 · matches ^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$

argumentsobjectrequired

idempotencyKeystringrequired

min length 1 · max length 64

ttlSecondsinteger

min 1 · max 300 · default: 30

Responses

202

Each device has an independent action or error

dataBroadcastResult[]required

Show properties

Array of BroadcastResult

deviceIdstring<uuid>required

actionActionReceipt

Show properties

idstring<uuid>required

deviceIdstring<uuid>required

capabilitystringrequired

argsobjectrequired

statusstringrequired

Allowed:queuedreceivedsucceededfailedexpiredcancelledunknown

createdAtintegerrequired

expiresAtintegerrequired

dispatchedAtinteger

resultany

clientKeystringrequired

Internal idempotency key stored in the action ledger; included by request/get/result handler responses.

fingerprintstringrequired

Internal canonical request fingerprint; included by request/get/result and action history responses.

principalIdstringrequired

Principal identifier associated with the action.

ownerAuthorizedbooleanrequired

Whether the action was directly authorized by an owner.

errorobject

Show properties

codestringrequired

messagestringrequired

400

Invalid request or validation failure

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

401

Missing or invalid credential

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

403

Insufficient access or grant

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

404

Resource not found

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

409

Individual device actions can conflict; inspect each result item

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

413

Request body exceeds the 16 KiB limit

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

429

Rate limit or workspace capacity limit

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

500

Internal error

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

503

Service or required integration is not configured

errorobjectrequired

Show properties

codestringrequired

messagestring

issuesobject[]

Show properties

Array of object

pathstring

messagestring

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (Clerk owner session)Remember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -X POST "${OPENLAUNCH_URL:-https://www.openlaunch.dev}/v1/broadcasts" -H "Authorization: Bearer $OPENLAUNCH_AGENT_TOKEN" -H 'Content-Type: application/json' -d '{"deviceIds":["00000000-0000-4000-8000-000000000001"],"capability":"device.health","arguments":{},"idempotencyKey":"broadcast-001"}'

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

curl -X POST 'https://www.openlaunch.dev/v1/broadcasts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "deviceIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "capability": "string",
  "arguments": {
    "property1": null,
    "property2": null
  },
  "idempotencyKey": "string",
  "ttlSeconds": 30
}'

const response: Response = await fetch("https://www.openlaunch.dev/v1/broadcasts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"deviceIds\": [\n    \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n  ],\n  \"capability\": \"string\",\n  \"arguments\": {\n    \"property1\": null,\n    \"property2\": null\n  },\n  \"idempotencyKey\": \"string\",\n  \"ttlSeconds\": 30\n}"
});

import requests

response = requests.post(
    "https://www.openlaunch.dev/v1/broadcasts",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"deviceIds\": [\n    \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n  ],\n  \"capability\": \"string\",\n  \"arguments\": {\n    \"property1\": null,\n    \"property2\": null\n  },\n  \"idempotencyKey\": \"string\",\n  \"ttlSeconds\": 30\n}",
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader("{\n  \"deviceIds\": [\n    \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n  ],\n  \"capability\": \"string\",\n  \"arguments\": {\n    \"property1\": null,\n    \"property2\": null\n  },\n  \"idempotencyKey\": \"string\",\n  \"ttlSeconds\": 30\n}")
	req, err := http.NewRequest("POST", "https://www.openlaunch.dev/v1/broadcasts", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

Response

{
  "data": [
    {
      "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",
      "action": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",
        "capability": "string",
        "args": {},
        "status": "queued",
        "createdAt": 0,
        "expiresAt": 0,
        "dispatchedAt": 0,
        "result": null,
        "clientKey": "string",
        "fingerprint": "string",
        "principalId": "string",
        "ownerAuthorized": true
      },
      "error": {
        "code": "string",
        "message": "string"
      }
    }
  ]
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}