Skip to content
HumanAI
Developers

Human AI API reference

Connect your devices, products and agents to the command plane with a simple, predictable REST API. JSON in, JSON out, and your first call takes minutes.

Get your API key Developer overview

Introduction

The Human AI API lets you report device telemetry, revenue and usage, list the devices in your fleet and launch missions from your own software. Every request and response body is JSON, and every endpoint lives under one base URL:

Base URL
https://human-ai-beryl.vercel.app/api/v1

Authentication

Authenticate every request with a secret API key sent as a bearer token. Create and revoke keys in the Human AI app under Settings → API keys. Live keys begin with hmn_live_.

Header
Authorization: Bearer hmn_live_YOUR_KEY

Keep your keys secret. Never embed them in client-side code or public repositories. If a key is exposed, revoke it immediately and create a new one.

Responses and errors

Successful requests return HTTP 200 with "ok": true plus any data for the endpoint. Failed requests return an appropriate HTTP status and a human-readable error message.

Success
{ "ok": true, ... }
Error
{ "error": "device_id is required" }
StatusMeaning
400The request body is missing a required field or a value is invalid.
401The API key is missing, invalid or revoked.
402The account has an open balance. Settle the invoice in the app to restore API access.
403The account is not permitted to perform this request.
404The resource, such as a device_id, was not found in your account.
500Something went wrong on our side. Retry safely with the same idempotency key.
POST/api/v1/telemetry

Send device telemetry

Report the latest state of a connected device. Updates appear instantly in your live fleet view and power alerts, insights and missions.

Body parameters
  • device_idstringrequired

    The ID of a device in your fleet.

  • batterynumber

    Battery level from 0 to 100.

  • statusstring

    Current status, for example online, idle, mission, charging or offline.

  • locationobject

    Position as { lat, lng, label? }.

  • metricsobject

    Any additional numeric or text readings, such as altitude_m or speed_kmh.

Request
curl -X POST https://human-ai-beryl.vercel.app/api/v1/telemetry \
  -H "Authorization: Bearer hmn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "DEVICE_ID",
    "battery": 87,
    "status": "online",
    "location": { "lat": 37.7749, "lng": -122.4194, "label": "North substation" },
    "metrics": { "altitude_m": 120, "speed_kmh": 42 }
  }'
Response
{ "ok": true }
POST/api/v1/revenue

Report revenue

Record a sale so it is attributed in your dashboard. Sending the same external_id twice is safe: duplicates are recognized and never counted twice.

Body parameters
  • amount_centsintegerrequired

    Sale amount in the smallest currency unit, for example 4900 for $49.00.

  • external_idstringrequired

    Your unique ID for the sale, such as an order or charge ID. Used for idempotency.

  • currencystring

    Three-letter ISO currency code, for example usd.

  • route_slugstring

    The tracking link slug that produced the sale, if any.

  • customer_emailstring

    The buyer's email address, used to connect the sale to its lead.

Request
curl -X POST https://human-ai-beryl.vercel.app/api/v1/revenue \
  -H "Authorization: Bearer hmn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 4900,
    "external_id": "order_10294",
    "currency": "usd",
    "route_slug": "a1B2c3D4",
    "customer_email": "buyer@example.com"
  }'
Response
{ "ok": true, "id": "…", "route_id": "…", "lead_id": "…" }

// When the external_id was already reported
{ "ok": true, "duplicate": true }
POST/api/v1/usage

Report usage

Record metered usage from your own apps and agents. Pass an idempotency_key to make retries safe.

Body parameters
  • metricstringrequired

    One of ai_message, mission, device_hour, route_scan, api_call or telemetry_event.

  • quantitynumber

    A positive quantity to record. Defaults to 1.

  • idempotency_keystring

    A unique key for this report. Repeated keys are ignored.

Request
curl -X POST https://human-ai-beryl.vercel.app/api/v1/usage \
  -H "Authorization: Bearer hmn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metric": "device_hour", "quantity": 3, "idempotency_key": "shift-2026-11-03-a" }'
Response
{ "ok": true }
GET/api/v1/devices

List devices

Return every device in your fleet with its current status, battery, location and live readings.

Request
curl https://human-ai-beryl.vercel.app/api/v1/devices \
  -H "Authorization: Bearer hmn_live_YOUR_KEY"
Response
{
  "ok": true,
  "devices": [
    {
      "id": "…",
      "kind": "drone",
      "name": "Survey Drone 14",
      "model": "…",
      "status": "online",
      "battery": 87,
      "autonomy_level": 4,
      "location": { "lat": 37.7749, "lng": -122.4194, "label": "North substation" },
      "live": { "altitude_m": 120, "speed_kmh": 42 },
      "last_seen_at": "2026-11-03T16:20:00Z"
    }
  ]
}
POST/api/v1/missions

Launch a mission

Describe an objective in plain language and Human AI plans and launches the mission. Optionally target a specific device.

Body parameters
  • objectivestringrequired

    What you want done, in plain language (at least 5 characters).

  • device_idstring

    Assign the mission to a specific device. Omit to let Human AI choose.

Request
curl -X POST https://human-ai-beryl.vercel.app/api/v1/missions \
  -H "Authorization: Bearer hmn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "objective": "Inspect the north substation roof and report anomalies", "device_id": "DEVICE_ID" }'
Response
{
  "ok": true,
  "mission": {
    "id": "…",
    "title": "Inspect the north substation roof",
    "status": "running",
    "device_id": "…",
    "plan": [ … ]
  }
}

Ready to build?

Create a free account, generate a key under Settings → API keys and make your first call in minutes.

Start free Talk to our team