queryhub

Message ingest API

Send a message from any server into the queryhub inbox. One endpoint, bearer-key auth, JSON in, JSON out.

Endpoint

POSThttps://query.easytrans.io/api/messages

Authentication

Every request needs an API key issued from the admin console, sent as a bearer token:

Authorization: Bearer <your api key>

Keys can be revoked at any time. Tokens are shown once at creation and stored server-side only as a hash.

Request body

JSON object, Content-Type: application/json.

Field	Type	Rules
body	string	required — the message content, max 16 KB (UTF-8 bytes)
title	string	optional, max 300 chars
source	string	optional, max 120 chars — e.g. the sending service's name
level	string	optional, one of info \| warn \| error (default info)

Response

On success: 201 Created

{"ok": true, "id": 1234}

Error codes

Status	Meaning
400	Malformed request — invalid JSON, missing `body`, field too long, or bad `level`. Response: `{"ok": false, "error": "..."}`
401	Missing, invalid, or revoked API key.
413	`body` exceeds the 16 KB limit.
429	Rate limit exceeded for this key. Back off and retry.

Rate limit

Each API key may send at most 60 requests per minute (sliding window). Exceeding it returns 429; there is no penalty beyond the window — just retry after a pause.

curl example

curl -sS https://query.easytrans.io/api/messages \
  -H "Authorization: Bearer $QUERYHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "nightly backup finished",
    "source": "backup-runner",
    "level": "info",
    "body": "backup OK: 4.2 GB in 181s, 0 errors"
  }'

python-requests example

import requests

resp = requests.post(
    "https://query.easytrans.io/api/messages",
    headers={"Authorization": f"Bearer {QUERYHUB_KEY}"},
    json={
        "title": "disk usage warning",
        "source": "monitor",
        "level": "warn",
        "body": "/dev/sda1 at 91% on web-1",
    },
    timeout=10,
)
resp.raise_for_status()          # 4xx/5xx -> exception
print(resp.json())               # {"ok": True, "id": 1234}

Health

GET/healthz → {"status": "ok"} (public, unauthenticated).