Quickstart

Read a simulated room in test mode, then switch to your Cymo by swapping the key.

Create a test key

Open the dashboard, go to API keys and create a key while in test mode. Set it as CYMO_API_KEY. Test keys start with cym_test_ and only ever read the simulator.

Make a request

Every test project has a simulated bedroom, room_bedroom. The response is { data, meta }, and meta.livemode is false.

terminal

curl "https://api.cymatics.tech/v1/vitals?room_id=room_bedroom" \
  -H "Authorization: Bearer $CYMO_API_KEY"

Install the SDK

$npm install @cymos/sdk

Requires Node.js 20.19 or later. The SDK guide covers options, pagination, streams, errors and retries.

Read vitals

agent.ts

import { Cymo } from "@cymos/sdk";

const cymo = new Cymo({ apiKey: process.env.CYMO_API_KEY! });

const { data, meta } = await cymo.vitals.get({ room_id: "room_bedroom" });
for (const person of data.people) {
  console.log(person.track_id, person.signals.heart_rate_bpm?.value);
}
console.log(meta.livemode); // false: test keys read the simulator

Stream a room

agent.ts

for await (const message of cymo.rooms.stream({ room_id: "room_bedroom" })) {
  console.log(message.kind, message.data);
}

Or use the CLI

cymatics login saves a key for your terminal. Every command prints the same JSON envelope, or one NDJSON line per message for streams.

$npm install -g @cymos/cli

terminal

$ cymatics login
$ cymatics vitals get --room room_bedroom --json
$ cymatics vitals stream --room room_bedroom --max-events 3

See the CLI guide for profiles, scenarios, the local simulator and webhook forwarding.

Connect an agent

mcp.json

{
  "mcpServers": {
    "cymo": {
      "url": "https://mcp.cymatics.tech/mcp",
      "headers": {
        "Authorization": "Bearer cym_test_…"
      }
    }
  }
}

The MCP server has one tool per API operation, named after it: get_room, get_vitals, create_scenario_run and so on. Each endpoint page names its tool. Tools call the API with your key, so its scopes, limits and metering apply. Add ?read_only=1 to the URL to list only tools that read.

Stream tools return a bounded window instead of an open stream: they stop after duration_ms (default 10 s, up to 60 s) or max_samples messages (default 20, up to 200) and say whether more followed. Raw radar bytes have no tool. The MCP guide has the setup for Claude, Cursor, VS Code, Codex and more.