BizKitHub
DocsAPI ReferenceInternal/api/v1/internal/log/
postInternalPublic API v1

/api/v1/internal/log/

First-party microservice log ingestion. Requires an API key issued under the internal organisation (id=1). Any other API key is rejected with HTTP 403.

This is where scout, pdf, proxy and other VPS/edge workers POST their own logs so the platform operator sees them side-by-side with core-emitted logs in the admin dashboard. The entry is written against the internal organisation and prefixed with [svc:<service>] so dashboard filters can group by originating service without needing a new column.

Why not reuse /tracking/log? /tracking/log writes to the caller's own organisation; a microservice would need a key for every tenant it touches. This endpoint always writes to the internal org regardless of the caller's key, which is the semantic microservices actually want.

internalpostApiV1InternalLog

Parameters

JSON body

Request body

application/json
servicestringRequired

Name of the microservice emitting the log. Free-form short slug — kebab-case, matches the subdomain or systemd unit. Prepended to the stored message as [svc:<name>] … so dashboard filters can group by it.

Length: 0–32
Examplesscoutscout:sync-blob-backuppdfproxycdn
messagestringRequired

Human-readable log body. For exceptions include the error class, message, and the smallest set of identifiers that reproduces the context (e.g. blob id, cron tick, HTTP method/URL). JSON is accepted but prefer flat text.

Examplessync-blob-backup tick crashed: ConnectionTimeoutError at pg pool acquire (after 212 iters, 847 blobs backed up)puppeteer launch failed: ENOENT /tmp/chromium (nodeVersion=v22.22.3, memoryMb=512)
codestringOptional

Application-defined log code (short slug). Groups related events for anomaly detection and links to docs.bizkithub.com/system-codes/<code>. Defaults to MSVC_LOG when omitted — but prefer a specific code (e.g. BLOB_BAK_CRASH, PDF_GEN_CRASH) so dashboards and runbooks can key off it.

Length: 0–64
ExamplesBLOB_BAK_CRASHPDF_GEN_CRASHPROXY_FORWARD_F
componentstringOptional

Sub-system that produced the log. Used for dashboard grouping. Typical values: cron, api, common.

Length: 0–32
Examplescronapi
subjectstringOptional

One-line summary used as the subject of any notification email dispatched for this log entry.

Length: 0–200
Examplescout sync-blob-backup worker crashed
level"info" | "success" | "warning" | "error" | "critical"Optional

Severity level. Defaults to info if omitted. Use error for a single failed operation, critical for a crash that stops the whole worker.

Values: infosuccesswarningerrorcritical
Exampleserrorcritical
sendNotificationbooleanOptional

When true, the log entry is eligible to trigger notifications (email) according to the internal-org notification rules. Use sparingly — most microservice entries are debounced and should NOT page.

Examplestruefalse
useDebounceobject | booleanOptional
One of 2:
Variant 1

Advanced debounce configuration. maxInterval defines maximum grouping window for duplicates (if omitted, backend uses a default interval).

enabledbooleanRequired

Enable/disable debouncing for this event. If omitted, the backend treats it as enabled.

Exampletrue
keystringOptional

Optional custom debounce key. When provided, logs sharing the same key will be grouped together (useful for dynamic messages).

Examplesstripe-webhook-timeoutdb-connection-failed
maxIntervalstring | numberRequired
One of 2:
Variant 1
string

Relative time interval expressed as a string.

Supported units and conversion (REAL_TIME_CHAR_TO_MINUTES):

Unit Name Minutes Notes
m minute 1
h hour 60
d day 1440 24h
w week 10080 7d
y year 525600 365d

Rules:

  • Units are case-insensitive and can be combined: 3w 4d 12h.
  • Decimal values are allowed: 0.5h, 2.5d.
  • Spaces and unit variants are tolerated: 10m, 10 min, 10 minutes.
  • Numeric value without a unit is interpreted as hours.

Rounding:

  • Result is returned in minutes and rounded up (Math.ceil).

Invalid or empty input returns 0.

Examples3w 4d 12h10m0.5h2.53,1
Variant 2
number

Relative time interval expressed as a number of minutes.

Rules:

  • Value is taken directly as minutes (e.g. 30 = 30 minutes).
  • No unit parsing or conversion is applied.
Examples30601501440
Variant 2
boolean

Simple debounce toggle. When true, repeated logs may be deduplicated/grouped within a backend-defined window. When false, debouncing is disabled and every event is stored.

Examplestruefalse

Response schema

1 status code documented

200Success
object | object
One of 2:
Variant 1
success"true"Required
Variant 2
success"false"Required
errorstringRequired

Response example

application/json
{
  "success": true
}

Request example

POST /api/v1/internal/log/

post
curl -X POST "https://api.bizkithub.com/api/v1/internal/log/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "service": "scout",
  "message": "sync-blob-backup tick crashed: ConnectionTimeoutError at pg pool acquire (after 212 iters, 847 blobs backed up)",
  "code": "BLOB_BAK_CRASH",
  "component": "cron",
  "subject": "scout sync-blob-backup worker crashed",
  "level": "error",
  "sendNotification": true
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key