boltZharp Docs
descriptionAPI Reference

Logs & Ingestion

Send logs from anything that can make an HTTP request, search them, manage the log sources your platforms drain into, and list the hosts running the agent.

Paths are relative to https://api.zharp.io/api/v1. Sending data uses an X-API-KEY header — an Ingest only key is made for this, though any key works. Searching and everything else uses Authorization: Bearer with a read key, or admin to change log sources. See Authentication.

Sending logs

From an app, a Zharp SDK sends logs for you — batched, retried, with the user and session — over OpenTelemetry. Anything else can send the requests below itself; see HTTP API for a walkthrough.

POST/agent/logs
Scope: ingest only or any key
Send a batch of log lines. Lines are stored within seconds; the answer comes as soon as they're accepted.

The key can go in the path instead, for senders that can't set headers: /agent/logs/<key>. Up to 10 MB a request, any number of lines; send X-Zharp-SDK: yourname/1.0 if you're writing a client.

Body (JSON)
logs
object[]required
The lines, each as below. A bare list, or a single line, works too.
logs[].message
stringrequired
The line. Anything else is turned into text; empty becomes (empty message).
logs[].timestamp
string | number
ISO 8601, or epoch seconds or milliseconds. Default: when it arrives.
logs[].service
string
The service it's filed under. Default unlabeled.
logs[].level
string
debug, info (default), warn, error, fatal — or warning, critical, syslog numbers and the like, which map onto those.
logs[].environment
string
Its environment tag — env works too.
logs[].version
string
Its version tag.
logs[].source
string
What wrote it — nginx, postgresql, json… — which picks how it's parsed. See parsed formats.
logs[].metadata
object
Anything else to keep with it. An error's stack here shows as a stack trace.
Request
curl -X POST "https://api.zharp.io/api/v1/agent/logs" \
  -H "X-API-KEY: $ZHARP_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "timestamp": "2026-10-26T09:12:01.000Z",
        "service": "checkout",
        "level": "error",
        "message": "Payment failed",
        "environment": "production",
        "version": "1.4.2",
        "source": "node",
        "metadata": { "orderId": "A-1042", "stack": "Error: card declined\\n    at charge (pay.js:42)" }
      }
    ]
  }'
Response
{ "statusCode": 200, "message": "Logs ingested successfully" }
Errors
  • 400No lines, or a field of the wrong type (level as a number, say).
  • 401No key, or a key that's invalid, disabled or expired.
  • 413A request over 10 MB — send smaller batches.
POST/logs/ingest
Scope: ingest only or any key
The same, as a plain list of lines — what most log shippers can be set up to send. Lines and limits are as above.
Body (JSON)
(body)
object[]required
The lines. { "logs": [...] } works too.
Request
curl -X POST "https://api.zharp.io/api/v1/logs/ingest" \
  -H "X-API-KEY: $ZHARP_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "service": "checkout", "level": "warn", "message": "Slow response from Stripe", "metadata": { "ms": 3200 } }]'
Response
{ "message": "Logs ingested successfully" }
Errors
  • 400No lines, or a field of the wrong type.
  • 401No valid key.
  • 413Over 10 MB.
info
Your log storage

Each plan keeps up to a set amount of logs at once: 3 GB on Free, 10 GB on Individual, 30 GB on Team, 200 GB on Business, unlimited on Enterprise. Logs are never refused for space: when storage is full, the newest are kept and the oldest deleted to make room. Only logs count; traces, metrics, errors and replays are kept for the retention. See Retention and storage, and current use with GET /workspaces/:id/usage.

Searching logs

GET/logs
Scope: readPermission: logs:view
Log lines, newest first, filtered any way you combine these. Only lines within the plan's retention are kept: 7 days on Free, 14 on Individual, 30 on Team, 90 on Business.

id is a string — the numbers are too large for JavaScript. Page with offset; there's no total. A line's parsed fields are in metadata.parsed, with the parser that read them in metadata.parser.

Query parameters
serviceName
string
A service — repeat it, or comma-separate, for several.
environment
string
An environment tag (env works too). Lists as above.
version
string
A version tag.
source
string
What wrote it: nginx, postgresql…
level
string
One level: error, warn…
search
string
Text in the message, ignoring case.
filter
string
A field condition on what was parsed from the line or its metadata: http.status_code>=500, client.ip=10.0.0.4, error.type:* (has it). Repeat for up to 10, all of which must hold.
from
string (ISO 8601)
From this time — no earlier than the retention allows.
to
string (ISO 8601)
Up to this time.
limit
integer
1–1000. Default 100.
offset
integer
Lines to skip, for paging. Default 0.
Request
curl "https://api.zharp.io/api/v1/logs?serviceName=checkout&level=error&filter=http.status_code%3E%3D500&limit=50" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{ "message": "Logs retrieved successfully", "data": [ {
    "id": "918273",
    "workspaceId": 3,
    "sourceId": null,
    "serviceName": "checkout",
    "environment": "production",
    "serviceVersion": "1.4.2",
    "source": "node",
    "level": "error",
    "message": "Payment failed",
    "timestamp": "2026-10-26T09:12:01.000Z",
    "metadata": { "orderId": "A-1042", "stack": "…" },
    "createdAt": "2026-10-26T09:12:01.512Z"
  } ] }
Errors
  • 400A value out of range, or a filter that can't be read.
GET/logs/facets
Scope: readPermission: logs:view
What's been logged recently: each service in each environment with its line count, versions and sources, and every environment, version and source seen.
Query parameters
hours
integer
How far back, 1–720. Default 24.
Request
curl "https://api.zharp.io/api/v1/logs/facets?hours=24" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{
  "message": "Log services retrieved",
  "data": {
    "hours": 24,
    "services": [{ "serviceName": "checkout", "environment": "production", "lines": 5120, "lastSeen": "…", "versions": ["1.4.2"], "sources": ["node"] }],
    "environments": ["production", "staging"],
    "versions": ["1.4.2"],
    "sources": ["node", "nginx"]
  }
}
GET/logs/services
Scope: readPermission: logs:view
Every service name the workspace has stored lines for.
Request
curl "https://api.zharp.io/api/v1/logs/services" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{ "message": "Log services retrieved", "data": ["api", "checkout", "unlabeled"] }

Excluding logs

A drop rule stops the workspace keeping logs it doesn't want — a cluster's system pods, health-check noise. Matching lines are dropped the moment they arrive, from every agent, SDK and log source: they aren't stored, don't reach the live tail and don't count toward your log storage. Lines already stored stay until they expire.

GET/logs/drop-rules
Scope: readPermission: logs:view
The workspace's drop rules, oldest first.
Request
curl "https://api.zharp.io/api/v1/logs/drop-rules" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{ "message": "Log drop rules retrieved", "data": [{ "id": 3, "field": "service", "pattern": "aws-ebs-*", "createdAt": "2026-10-27T09:12:00.000Z" }] }
POST/logs/drop-rules
Scope: adminPermission: workspace:edit
Stop keeping logs that match. Takes effect within 30 seconds.
Body (JSON)
field
stringrequired
service, environment, source or message.
pattern
stringrequired
For a service, environment or source: the whole value, any case, with * matching anything — aws-ebs-*, kube-*. For a message: text it contains, any case (not a regex). Up to 200 characters; a pattern that is only * is refused.
Request
curl -X POST "https://api.zharp.io/api/v1/logs/drop-rules" \
  -H "Authorization: Bearer $ZHARP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "field": "service", "pattern": "aws-ebs-*" }'
Response
{ "message": "Matching logs will no longer be kept", "data": { "id": 3, "field": "service", "pattern": "aws-ebs-*", "createdAt": "…" } }
Errors
  • 400An unknown field, an empty or too-broad pattern, or more than 100 rules.
  • 409The same rule already exists.
DELETE/logs/drop-rules/:id
Scope: adminPermission: workspace:edit
Keep matching logs again, from now on.
Path parameters
id
integerrequired
The rule's id.
Request
curl -X DELETE "https://api.zharp.io/api/v1/logs/drop-rules/3" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{ "message": "Matching logs will be kept again", "data": null }
Errors
  • 404No such rule in this workspace.

Log sources

A log source is a URL a platform drains its logs into — Vercel, Render, Heroku, Fly.io, Cloudflare, AWS CloudWatch and others. Each has its own token, so you can roll or remove one without touching the rest. See Logs from hosting providers.

providerPlatform
vercel, netlify, render, flyio, railway, heroku, digitaloceanHosting platforms' log drains
cloudflare, supabaseLogpush and Supabase log drains
aws-cloudwatch, gcp-logging, azure-monitorCloud providers' log export
docker-logs, k8s-logs, datadog-forwarderContainers and forwarders
GET/log-sources
Scope: readPermission: logs:view
The workspace's log sources, with whether each is receiving and how fast.

status is waiting (nothing yet), receiving (lines in the last 5 minutes) or idle. token is masked unless the key is admin and its owner isn't Read-only. GET /log-sources/:id adds the last day's line count.

Query parameters
provider
string
Only this provider's.
Request
curl "https://api.zharp.io/api/v1/log-sources" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{
  "message": "Log sources retrieved",
  "data": [{ "id": 4, "provider": "vercel", "name": "Vercel", "token": "zh_src_9f…", "lastReceivedAt": "…", "createdAt": "…", "status": "receiving", "linesPerMin": 12.4 }]
}
POST/log-sources
Scope: adminPermission: monitors:edit
Create a log source and its token. Set the drain URL in your platform to /ingest/<provider>/<token>.
Body (JSON)
provider
stringrequired
One of the providers above.
name
string
Up to 120 characters. Default: the platform's name.
Request
curl -X POST "https://api.zharp.io/api/v1/log-sources" \
  -H "Authorization: Bearer $ZHARP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "vercel",
    "name": "Vercel — production"
  }'
Response
{ "message": "Log source created", "data": { "id": 4, "provider": "vercel", "name": "Vercel — production", "token": "zh_src_9f2c…", "status": "waiting", "linesPerMin": 0, … } }
Errors
  • 400An unknown provider, or a name that's too long.
POST/log-sources/:id/roll
Scope: adminPermission: monitors:edit
Give a source a new token. The old one stops working at once — update the drain URL in your platform.

DELETE /log-sources/:id removes a source; lines it already sent stay.

Path parameters
id
integerrequired
The log source's id.
Request
curl -X POST "https://api.zharp.io/api/v1/log-sources/4/roll" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{ "message": "Log source token rolled", "data": { "id": 4, "token": "zh_src_51ab…", … } }
Errors
  • 404No such source in this workspace.
POST/ingest/:provider/:token
Scope: token in the URL
Where a platform drains its logs. The provider's own format is read — NDJSON, logplex, Firehose, gzip — so set this URL in the platform; you don't call it yourself.

Up to 5,000 lines a request; more are dropped and counted in truncated.

Path parameters
provider
stringrequired
The source's provider.
token
stringrequired
The source's token. It can also come as Authorization: Bearer, an X-Zharp-Token header or ?token=, for platforms that put it there.
Request
curl -X POST "https://api.zharp.io/api/v1/ingest/vercel/zh_src_9f2c…" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary $'{"message":"GET / 200","projectName":"shop"}\n'
Response
{ "received": 1 }
Errors
  • 401A missing token, or one for another source or provider.
  • 413Over 10 MB.

Traces

Traces, and logs sent with them, go to Applications over OpenTelemetry: POST /otlp/v1/traces and POST /otlp/v1/logs under the same base URL, as OTLP/HTTP with Authorization: Bearer <key>. See OpenTelemetry for the endpoint, headers, attributes and responses, or use a Zharp SDK, which sends them for you.

Agents

GET/agent/list
Scope: read
Hosts, containers and clusters running the Zharp agent, most recently seen first.
  • status: active (seen in the last 2 minutes), idle, or offline after 15.
  • kind: host, docker, kubernetes or sidecar.
  • GET /agent/databases lists the databases agents report, for private database monitors.
  • PATCH /agent/:id/rename with { "name": "web-prod" } (an admin key) sets its display name; an empty name goes back to the hostname.
Request
curl "https://api.zharp.io/api/v1/agent/list" \
  -H "Authorization: Bearer $ZHARP_API_KEY"
Response
{
  "statusCode": 200,
  "message": "Agents retrieved successfully",
  "data": [{ "id": 3, "hostname": "web-01", "customName": null, "os": "linux", "version": "1.6.2", "kind": "host", "status": "active", "lastSeenAt": "…", "metrics": { … } }]
}