Logs API

Use the logs endpoint to send flat numeric events.

Endpoint


POST /v1.0/logs

Hosted default:


https://logs.chirpier.co/v1.0/logs

Request body

Send an array of logs.

Each log object supports:

log_id
agent
event
value
occurred_at
meta

Example:


[
  {
    "event": "task.duration_ms",
    "agent": "openclaw.main",
    "value": 420,
    "occurred_at": "2026-04-08T18:25:43Z",
    "meta": {
      "task_name": "email_triage",
      "result": "success"
    }
  },
  {
    "event": "tool.errors.count",
    "agent": "openclaw.main",
    "value": 1,
    "meta": {
      "tool_name": "crm.lookup"
    }
  }
]

Field notes

Field	Required	Description
`log_id`	No	UUID. If omitted, Chirpier generates a UUIDv7.
`agent`	No	Producer identity. Part of the event definition identity alongside `event`.
`event`	Yes	Flat event name (e.g., `task.duration_ms`).
`value`	Yes	Numeric value. Must be finite (not NaN or Infinity).
`occurred_at`	No	ISO 8601 timestamp. Defaults to `now`. Must be within the last 30 days and no more than 1 day in the future.
`meta`	No	JSON object or value. Maximum 1 KB. Object-shaped values can have at most 10 top-level keys.

Validation rules

Hard API maximum: 250 logs per request
event is required and must be non-empty after trimming whitespace
value must be a finite number
occurred_at must be within the last 30 days and no more than 1 day in the future
meta must be valid JSON, max 1 KB, max 10 top-level keys if object-shaped
Blank log_id values are replaced with generated UUIDs

Unknown agent + event pairs are auto-created as event definitions on first log. There is no manual registration step.

Example request

Raw API


curl -X POST "https://logs.chirpier.co/v1.0/logs" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "event": "task.duration_ms",
      "agent": "openclaw.main",
      "value": 420,
      "meta": {"task_name": "email_triage"}
    }
  ]'

JavaScript


import { createClient } from "@chirpier/chirpier-js";
 
const client = createClient({ key: process.env.CHIRPIER_API_KEY! });
 
await client.log({
  agent: "openclaw.main",
  event: "task.duration_ms",
  value: 420,
  meta: { task_name: "email_triage" },
});
 
await client.flush();
await client.shutdown();

Python


from chirpier import Log, new_client
 
client = new_client(api_key="chp_your_api_key")
client.log(
    Log(
        agent="openclaw.main",
        event="task.duration_ms",
        value=420,
        meta={"task_name": "email_triage"},
    )
)
client.flush()
client.close()

Go


ctx := context.Background()
 
client, err := chirpier.NewClient(chirpier.Options{Key: "chp_your_api_key"})
if err != nil {
    return err
}
defer client.Close(ctx)
 
if err := client.Log(ctx, chirpier.Log{
    Agent: "openclaw.main",
    Event: "task.duration_ms",
    Value: 420,
    Meta: map[string]any{"task_name": "email_triage"},
}); err != nil {
    return err
}
 
if err := client.Flush(ctx); err != nil {
    return err
}

Responses

200 OK with an empty body when the batch was accepted
400 Bad Request for validation failures
401 Unauthorized for invalid bearer tokens
503 Service Unavailable if the publisher queue is overloaded

Use one of the SDKs when you want batching, retry handling, and a single client for both logs and control-plane APIs.