API Reference

The numbrs API is a simple HTTP REST API for pushing metric data. It’s intentionally minimal — one endpoint, one job.

Base URL

https://numbrs.lol/api

If you’re self-hosting, replace this with your Vercel deployment URL.

Authentication

All API requests require an API key passed as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Find your API key under Settings → API Keys in the numbrs app.

---

POST /ingest

Push one or more metric data points.

Single metric

Request body:

{
  "metric": "server.cpu_pct",
  "value": 23.4,
  "timestamp": "2025-03-25T20:00:00Z",
  "tags": {
    "host": "mac-mini"
  }
}

Fields:

Field	Type	Required	Description
metric	string	yes	Metric name. Dot-separated recommended, e.g. server.cpu_pct
value	number	yes	The numeric value to record
timestamp	ISO 8601 string	no	When the measurement was taken. Defaults to current server time.
tags	object	no	Key-value string pairs. Used for filtering in dashboards.

Example:

curl -X POST https://numbrs.lol/api/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"metric": "server.cpu_pct", "value": 23.4, "tags": {"host": "mac-mini"}}'

Batch metrics

Send up to 100 metrics in a single request using an array:

[
  {"metric": "server.cpu_pct",     "value": 23.4, "tags": {"host": "mac-mini"}},
  {"metric": "server.mem_used_gb", "value": 6.1,  "tags": {"host": "mac-mini"}},
  {"metric": "server.disk_free_gb","value": 89.2, "tags": {"host": "mac-mini"}}
]

Example:

curl -X POST https://numbrs.lol/api/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '[
    {"metric": "server.cpu_pct",     "value": 23.4},
    {"metric": "server.mem_used_gb", "value": 6.1}
  ]'

Response

Success (200 OK):

{"ok": true}

Error (400 Bad Request):

{
  "error": "Invalid request body",
  "details": "value must be a number"
}

Response codes

Code	Meaning
200	Data accepted and stored
400	Bad request — malformed JSON or invalid field types
401	Missing or invalid API key
422	Validation error — required fields missing or wrong type
429	Rate limited — too many requests, back off and retry
500	Server error — retry after a short delay

---

Rate limits

The ingest endpoint accepts up to 60 requests per minute per API key. Use batch requests when pushing multiple metrics to stay well within limits.

If you exceed the rate limit, you’ll receive a 429 response with a Retry-After header indicating when you can retry.

---

Metric naming

There are no enforced naming rules, but a consistent source.category.name pattern makes dashboards much easier to work with:

server.cpu_pct
server.disk.used_gb
github.myrepo.deploy_count
bitcoin.price_usd
home.temp_c

Lowercase with underscores for word separation. Dots for hierarchy.

---

Related

• Custom Metrics — examples, use cases, and collector scripts
• Dashboard Builder — visualizing your data
• Troubleshooting — fixing common issues