Examples

These examples use http://127.0.0.1:47800, which works on your Mac. From another device, use the address in Where to send events. Replace hive_… with your key.

Just announce something

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Backup finished", "message": "Nightly backup took 14 minutes."}'

{"id": 12}

Urgent, with a notification

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Dogs out", "message": "Both dogs are past the side gate",
       "importance": "urgent", "push": true}'

Urgent events go to the top of Activity under Needs attention and stay there until you acknowledge them.

Ask an agent to act on it

Give it to the coordinator ("hive"), which can bring in any agent:

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Car arriving", "data": {"plate": "ABC123"},
       "agent": "hive", "prompt": "ABC123 is Sarah'\''s car. Say who has arrived in one short sentence."}'

The coordinator’s answer (“Sarah has arrived!”) is posted to Activity under the event.

Ignore repeats

A camera might see the same car in every frame. Send a dedupe key, and repeats within cooldown seconds (5 minutes by default) are logged but ignored:

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Car arriving", "data": {"plate": "ABC123"},
       "dedupe": "car-ABC123", "cooldown": 600}'

{"id": 3, "deduped": true}

Send a picture

Pictures go in image as a base64 data: URL, up to 256 KB:

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Someone at the door",
       "image": "data:image/jpeg;base64,'"$(base64 < snap.jpg | tr -d '\n')"'"}'

The picture is shown in Activity and Recent events (click it to enlarge). Shrink big photos first, for example with sips -Z 640 snap.jpg.

Python

import json
import urllib.request

def send_event(**event):
    request = urllib.request.Request(
        "http://127.0.0.1:47800/api/events",
        data=json.dumps(event).encode(),
        headers={"Authorization": "Bearer hive_…", "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)

send_event(title="Plant needs water", data={"moisture": 12}, importance="high")

Node.js

const response = await fetch('http://127.0.0.1:47800/api/events', {
  method: 'POST',
  headers: { Authorization: 'Bearer hive_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Build failed', message: 'main is red', importance: 'high', push: true }),
});
console.log(response.status, await response.json());

Home Assistant

Add a REST command to configuration.yaml:

rest_command:
  agent_city_event:
    url: "http://<your-mac's-address>:47801/api/events"
    method: POST
    headers:
      Authorization: "Bearer hive_…"
    content_type: "application/json"
    payload: >
      {"title": "{{ title }}", "message": "{{ message }}", "push": true}

Then call it from an automation:

action: rest_command.agent_city_event
data:
  title: "Garage door open"
  message: "The garage door has been open for 10 minutes."

Turn on Let paired phones connect in Settings → Devices → Phones first, so the network port is open.

Apple Shortcuts

Use the Get Contents of URL action:

• URL: http://127.0.0.1:47800/api/events
• Method: POST
• Headers: Authorization = Bearer hive_…
• Request Body: JSON, with a title and anything else you need

Start an automation

curl -X POST http://127.0.0.1:47800/api/events \
  -H "Authorization: Bearer hive_…" \
  -H "Content-Type: application/json" \
  -d '{"workflow": "Car arrives", "data": {"plate": "ABC123"}}'

See Starting automations.