Skip to content

Getting started

This guide takes a brand-new Raclip device from the box to your first programmatically retrieved recording in under fifteen minutes — no account setup, no app install.

What you need

  • A Raclip device (still in the box is fine).
  • A Wi-Fi network you can connect the device to.
  • Optional, only for the SDK path: Python 3.10+ or Node.js 18+. Any HTTP client works equally well.

1. Claim your device

Every Raclip ships with a printed QR code on the front of the device.

  1. Find the QR code on the front of your unit.
  2. Open your phone's camera and point it at the QR code. Tap the link that pops up.
  3. The link opens console.raclip.ai and automatically creates an account for you if you don't already have one. No signup form, no email confirmation step.
  4. Confirm the claim. The device is now bound to your organization.

The device appears under Devices in the console. Tag it with a unit, location, employee, or custom metadata in the next step — or skip ahead and configure it later.

2. Connect to Wi-Fi

Every Raclip ships already in setup mode. The first time you power it on, it immediately broadcasts its own Wi-Fi network so you can configure your real one — no app required.

Power the device on

Press the On/Off button. Within a few seconds the LED begins alternating white and blue — that's setup mode.

Join the device's Wi-Fi

The device broadcasts its own temporary Wi-Fi network during setup:
SSID RaClip-Setup
Password raclip-admin
  1. On your phone (or laptop), open Wi-Fi settings.
  2. Connect to RaClip-Setup.
  3. Your operating system should detect the captive portal and open the configuration page automatically. If it doesn't, open a browser and visit http://192.168.4.1/.

Configure your network

In the captive portal:

  1. Pick your home / office Wi-Fi network from the dropdown (or type it manually if it's hidden).
  2. Enter the password.
  3. Tap Save & Reboot.

The device reboots. After ~10 seconds:

  • Solid blue LED → device is connected and ready.
  • Fast magenta flash → registration failed. Double-check your Wi-Fi password and try again.

Need to reconfigure later?

To put a previously configured device back into setup mode, hold the Start/Stop button for 10 seconds. The device clears its stored Wi-Fi credentials and reboots into setup mode.

To push additional networks over the air without rebooting (e.g. for fleet deployments or multi-site users), see Push Wi-Fi networks over the air.

3. Assign the device

Assignment lets you tag a device with the unit, location, person, and any custom metadata that should travel with its recordings. Every field is optional — recordings work without an assignment, but assignment makes filtering, billing, and analytics far easier.

Assign in the console

  1. Sign in to https://console.raclip.ai.
  2. Click Devices in the top nav.
  3. Find your device in the list and click Assign.
  4. Fill in any combination of:
    • Unit ID — a logical unit, department, team, or fleet identifier (e.g. ICU-01, LEGAL-TEAM-3, TRUCK-14).
    • Location ID — a physical location (e.g. ROOM-301, FLOOR-2, SITE-WEST).
    • Employee ID — the person operating the device.
    • Custom Fields — arbitrary key/value pairs for anything else (department: Cardiology, cost-center: 4290, vehicle-class: Class-A, …). Click Add Field for as many as you need.
  5. Click Assign Device.

Reassign at any time

Assignments are mutable. Reassign the same device to a different unit/location/employee whenever its role changes — recordings made before the change keep the old metadata, recordings made after pick up the new.

The same fields are available on every device record returned by the API (unit_id, location_id, employee_id, custom_fields).

4. Get an API key

API keys authenticate your application to the Raclip API. They're scoped to your organization, generated in the console, and shown to you exactly once.

Generate a key

  1. Sign in to https://console.raclip.ai.
  2. Click API Keys in the top nav.
  3. Click Create key. Give it a label (e.g. production-app, local-dev) so you can tell keys apart later.
  4. Copy the key. It's shown once. If you lose it, revoke and create a new one.

The key looks like:

raclip_prod_a1b2c3d4e5f6g7h8_9ijklmno

Store it as an environment variable

Don't paste keys into source code. Store the key in RACLIP_API_KEY and read it from the environment:

export RACLIP_API_KEY="raclip_prod_a1b2c3d4e5f6g7h8_9ijklmno"

Both SDKs read this automatically. With curl, pass it as a Bearer token:

curl -H "Authorization: Bearer $RACLIP_API_KEY" https://api.raclip.ai/api/raclip/calls/<device_id>/latest

Scope and rotation

  • Org-scoped. Your key works against any device in your organization. You never send org_id in requests.
  • Rotate freely. Create a new key, deploy it, then revoke the old one. Up to 5 active keys per org at a time.
  • One key per environment. Use separate keys for production, staging, and local dev so you can revoke each independently.

5. Record and fetch audio

You have a claimed, online device with a solid blue LED, and an API key in RACLIP_API_KEY. Time to record something.

Record on the device

The device has three buttons:

Button Action
On/Off Press to toggle the device on or off.
Start/Stop Press to start recording. Press again to pause or resume.
Send Press to end the recording and upload it.

A typical encounter:

  1. Press Start/Stop. LED turns solid magenta — recording.
  2. (Optional) Press Start/Stop again to pause. LED slow-blinks blue. Press Start/Stop once more to resume.
  3. When the encounter is over, press Send. LED turns solid cyan — uploading.
  4. When the upload completes, the LED returns to solid blue.

The recording is now available through the API, attached to the device that recorded it.

Fetch the recording

Several ways to grab it. The HTTP API is the product; the SDKs are thin wrappers around the same endpoints. Pick whichever fits your stack.

Get the most recent recording for a device:

curl -H "Authorization: Bearer $RACLIP_API_KEY" \
  https://api.raclip.ai/api/raclip/calls/<device_id>/latest

The response includes a short-lived download_url:

{
  "call_id": "abc123",
  "device_id": "8f1a…",
  "duration_seconds": 42.7,
  "created_at": "2026-04-29T10:30:45Z",
  "download_url": "https://…?signature=…"
}

Download the audio — the download_url must not carry the Authorization header:

curl -L -o recording.mp3 "<download_url>"

Install the SDK:

pip install raclip
# or
uv add raclip

Fetch the latest recording and save it to disk:

from raclip import Client

with Client() as client:
    devices = client.devices.list()
    device_id = devices.devices[0].device_id

    latest = client.calls.latest(device_id)
    print(f"call {latest.call_id} — {latest.duration_seconds:.1f}s")

    client.calls.download(device_id, latest.call_id, dest="recording.mp3")

The SDK reads RACLIP_API_KEY from the environment automatically.

Install the SDK:

npm install @raclip/sdk

Fetch the latest recording and save it to disk:

import { Client } from '@raclip/sdk'

const client = new Client()
const devices = await client.devices.list()
const deviceId = devices.devices[0].device_id

const latest = await client.calls.latest(deviceId)
console.log(`call ${latest.call_id} — ${latest.duration_seconds.toFixed(1)}s`)

await client.calls.download(deviceId, latest.call_id, 'recording.mp3')

The SDK reads RACLIP_API_KEY from the environment automatically.

Anything that speaks HTTP works. Set the Authorization: Bearer … header on requests to https://api.raclip.ai/api/…, parse JSON responses, follow download_url with no Authorization header. The full endpoint catalog is in the API reference.

6. Webhooks (optional)

Skip polling — let recordings push to your server as soon as they're available.

Configure a webhook

  1. Sign in to https://console.raclip.ai.
  2. Click Webhooks in the top nav.
  3. Enter:
    • URL — the HTTPS endpoint that will receive events.
    • Secret — a shared string (8+ chars) used to sign each delivery so you can verify authenticity.
  4. Save. The webhook is enabled immediately.

Verify a delivery

Every delivery includes an HMAC-SHA256 signature in the X-Webhook-Signature header:

import hmac, hashlib

def verify(headers: dict, body: bytes, secret: str) -> bool:
    signature = headers.get("X-Webhook-Signature", "")
    timestamp = headers.get("X-Webhook-Timestamp", "")
    if not signature or not timestamp:
        return False

    signed_payload = f"{timestamp}.".encode("utf-8") + body
    expected = hmac.new(
        secret.encode("utf-8"), signed_payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, f"sha256={expected}")

Always pass the raw body bytes, not a re-serialized JSON string — even a single whitespace difference will fail verification.

What's in the payload

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "recording.completed",
  "created_at": "2026-04-29T10:30:45Z",
  "data": {
    "device_id": "8f1a…",
    "call_id": "abc123",
    "duration_seconds": 42.7,
    "presigned_url": "https://…?signature=…",
    "presigned_url_expires_at": "2026-04-29T11:30:45Z"
  }
}

The payload includes a presigned_url ready to download — for many use cases, you can stream the audio straight into your processing pipeline without a follow-up API call.

For the full delivery contract (every header, retry policy, signature algorithm), see the Webhooks API reference.

7. Push Wi-Fi networks over the air

Once a device is online, you don't need physical access to add or change its Wi-Fi networks. Update the network list from the console and the device picks it up on its next heartbeat.

Manage networks per device

  1. Sign in to https://console.raclip.ai.
  2. Click Devices in the top nav and select your device.
  3. Open the Wi-Fi tab.
  4. Click + Add Network, then enter:
    • SSID — the network name.
    • Priority — 0 is the primary network. Higher numbers are tried in order if the primary is unreachable.
  5. Save. The page shows the device's current network list and the config version, which bumps on every change.

To remove a network, click the trash icon in its row.

When changes apply

The device polls for config changes on its next heartbeat (~5 minutes). Updates take effect via hot reconnect — no reboot, no interruption to recordings already in progress. If the device is currently connected to a network you remove, it'll switch to the next-priority network on the next heartbeat.

Why priorities matter

A device can roam between sites, vehicles, or networks throughout the day. Set the most reliable network at priority 0, then list backups in order. The device tries each in priority order and stays on the first one it can join.

Examples:

  • Multi-site clinic: Clinic-Main (priority 0) → Clinic-Annex (1) → owner's hotspot (2).
  • Field vehicle: Truck-Modem (0) → Site-Wifi (1).
  • Construction: Trailer-LTE (0) → Site-WiFi-East (1) → Site-WiFi-West (2).

You can update the list at any time — the device just reads the latest config on every heartbeat.

What's next