Events · sendEvent

Send an event

POST /v1/events

Something an agent reports that needs no action ("Deploy finished"). Shown in the inbox and delivered like an ask, without options; muted projects and quiet hours hold its delivery. With a test API key (lg_test_…) it is test: true: shown in the app, never delivered.

Who may call it: Agents (API key)
Server: https://api.logu.dev

Parameters#

Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	optional	Send a unique value per operation to retry safely: a retry with the same key and body returns the first result (`Idempotent-Replayed: true`). Per agent, remembered 24 hours. · e.g. `deploy-4821`

Request body#

Content type application/json (required).

What an agent sends to report an event. Strict.

Field	Type	Required	Notes
`project`	`string`	required	1–64 chars · pattern `^[a-z0-9][a-z0-9._-]*$`
`channel`	`string`	optional	1–64 chars · pattern `^[a-z0-9][a-z0-9._-]*$`
`title`	`string`	required	1–200 chars
`body`	`string`	optional	0–10000 chars
`icon`	`string`	optional	1–16 chars
`url`	`string`	optional	uri
`metadata`	`object`	optional	Free-form context stored with the item, up to 8,192 characters of JSON. `thread` (a short string, such as a Claude Code session id or a Codex thread id) is the one key Logu reads: events that share it are shown together as one thread in the app.
`attachments`	`string[]`	optional	0–4 items

{
  "project": "shop",
  "title": "Deploy finished",
  "body": "v1.4 is live.",
  "icon": "🚀",
  "url": "https://shop.example.com"
}

Example#

curl -s -X POST "https://api.logu.dev/v1/events" \
  -H "Authorization: Bearer $LOGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"shop","title":"Deploy finished","body":"v1.4 is live.","icon":"🚀","url":"https://shop.example.com"}'

Responses#

201

The event. A replayed idempotent retry answers 200 with the original.

{
  "id": "evt_01K7DQ2Z9X4M6P8R1T3V5W7Y9A",
  "project": "shop",
  "channel": null,
  "title": "Deploy finished",
  "body": "v1.4 is live.",
  "icon": "🚀",
  "url": "https://shop.example.com",
  "metadata": null,
  "agent": {
    "id": "agt_01K7D8F2H4K6M8P0R2T4V6X8Z0",
    "name": "deploy-bot"
  },
  "attachments": [],
  "test": false,
  "createdAt": "2026-10-12T14:03:11.000Z"
}

Response fields

Field	Type	Required	Notes
`id`	`string`	required
`project`	`string`	required
`channel`	`string \| null`	required
`title`	`string`	required
`body`	`string \| null`	required
`icon`	`string \| null`	required
`url`	`string \| null`	required
`metadata`	`object \| null`	required	Free-form context stored with the item, up to 8,192 characters of JSON. `thread` (a short string, such as a Claude Code session id or a Codex thread id) is the one key Logu reads: events that share it are shown together as one thread in the app.
`agent`	`AgentRef \| null`	required
`agent.id`	`string`	required
`agent.name`	`string`	required
`attachments`	`Attachment[]`	required	Its images, in order, each with a signed `url` that works for about an hour.
`attachments[].id`	`string`	required
`attachments[].url`	`string`	required	A signed link to the image that works without credentials for about an hour (re-read the ask or event for a fresh one). Members can always fetch it with `GET /v1/attachments/{id}`.
`attachments[].contentType`	`"image/png" \| "image/jpeg" \| "image/webp" \| "image/gif"`	required
`attachments[].size`	`integer`	required	Bytes.
`attachments[].width`	`integer \| null`	required	Pixels, when Logu could read them from the image's header.
`attachments[].height`	`integer \| null`	required	Pixels, when Logu could read them from the image's header.
`attachments[].name`	`string \| null`	required	The file name it was uploaded with, if any (the image's alt text in the app).
`test`	`boolean`	required	Sent with a test API key (`lg_test_…`): shown in the app, never delivered.
`createdAt`	`string`	required	date-time

Errors#

Every error is {"error":{"code","message","hint","docUrl","requestId"}}: branch on code. See Errors.

Status	Code	Meaning
400	`bad_request`	The request is malformed or a field is invalid (see `issues`).
400	`unknown_field`	The body has a field the endpoint doesn't know (often a typo or snake_case).
401	`unauthorized`	No credentials, or the API key or session is invalid or revoked.
402	`plan_limit`	This is over one of the workspace's plan quotas: asks, events or metric reports this month, stored images, projects or metric names (Free and Pro), or on Free its agents, members and webhook endpoints (only on servers that enforce plan limits), or a Free account that already owns its shared workspaces (always).
402	`ceiling_reached`	The workspace reached one of Logu's cost ceilings (asks, events, metric reports, test traffic or images this month, stored image bytes, projects, metric names or API keys). Unlike `plan_limit`, upgrading doesn't lift it. An account that already owns the most shared workspaces an account may own gets it too.
403	`forbidden`	The caller is authenticated but may not do this (wrong role, or an API key on a human-only endpoint).
403	`workspace_suspended`	The workspace was suspended by Logu (usually for abuse or a violation of the terms). Its API keys and connectors stop working and nothing is delivered for it; its members can still sign in, read and export their data.
409	`idempotency_key_in_use`	A request with the same idempotency key is still being processed.
422	`idempotency_key_reused`	The idempotency key was already used with a different request body or endpoint.
429	`rate_limited`	This API key sent too many requests, or a human did too much too fast: sign-in attempts, workspaces created in a day, or a global daily cap on new accounts was reached.
500	`internal_error`	Something went wrong on Logu's side.