API reference
The Logu HTTP API at https://api.logu.dev, version 1.0.0. Generated from the OpenAPI 3.1 document: openapi.json.
- AsksAn ask is an agent's request for a human decision. Agents ask and wait; only a human Decider or Owner decides.
- EventsAn event is something an agent reports that needs no action. Delivered like an ask, without options.
- AttachmentsAn attachment is an image an agent adds to an ask or event (up to 4), e.g. a UI change's before/after screenshots. Upload it, then list its id in attachments. Private to the workspace; shown with signed links that expire.
- MetricsA metric is a named number an agent reports over time; Insights shows trends and threshold alerts.
- AgentsAgents and their API keys. An agent is anything that calls Logu from code; it belongs to a workspace.
- WorkspacesA workspace owns everything agents send. Every human has a personal workspace and can join others.
- MembersMembers of a workspace and their roles: Owner, Decider, Viewer.
- InvitationsAn Owner invites an email address with a role; a one-time link valid 7 days.
- WebhooksWebhook endpoints get what agents send (asks created and settled, events, threshold alerts) as signed POSTs (Standard Webhooks), retried for about 28 hours, with a delivery log. Owners manage them. See https://logu.dev/docs/webhooks.
- BillingA workspace's plan: Free or Pro (US$ 29/month, founder prices for the first 1,000 workspaces). Owners upgrade with Stripe Checkout and manage the subscription in Stripe's Customer Portal. Over a plan quota (while limits are enforced) the API answers 402 plan_limit; over one of Logu's always-on cost ceilings, 402 ceiling_reached. See https://logu.dev/docs/billing.
- RulesA rule is an Owner's decision made in advance: asks from one agent in one project (with an exact title, when set) that offer its option are decided with it as they're sent, by that Owner (decidedVia: "rule"). Owners create and delete them in the app; API keys never can.
- ActivityThe activity log: who did what in a workspace.
- DeliveryHow Logu reaches each member: push, browser notifications, email, Telegram, Slack, WhatsApp, quiet hours and project mutes. Per member, across workspaces.
- MeWho is calling.
- Sign-inHow humans get a session token (under /api/auth, not /v1): magic links, passkeys, email + password, and their sessions. Agents use API keys instead.
- MetaDiscovery for agents and tools: this document, the reference page, llms.txt and MCP.
Overview#
Logu is where software agents reach a human. Agents ask. You decide. An agent sends an ask when it needs a decision, an event when something happened and a metric when it reports a number; the human gets them by push, browser notifications, email, Telegram, Slack and WhatsApp, and decides from wherever they are. Agents never decide.
For agents: read x-agent-hint on each operation. The core loop is POST /v1/asks, then GET /v1/asks/{id}/wait?timeout=50 while status is waiting. Guide: https://api.logu.dev/llms.txt (full: https://api.logu.dev/llms-full.txt). MCP: https://api.logu.dev/mcp.
Auth. Agents send an API key (Authorization: Bearer lg_…) and always act in its workspace. Humans send their session token and pick a workspace with Logu-Workspace (default: their personal one). x-logu-access on each operation says who may call it (human: the least role, account for any signed-in human; agent: whether an API key may).
Requests. JSON, camelCase. Request bodies are strict: an unknown field is a 400 unknown_field with a "did you mean". Send Idempotency-Key on POST /v1/asks, /v1/events and /v1/metrics to retry safely (per agent, 24 hours).
Limits. Per API key, per minute: 60 asks, 600 events and metrics, 120 images, 1200 requests in all (429 rate_limited with Retry-After). Humans aren't rate limited.
Retention. Settled asks are deleted 180 days after they settled and events 180 days after they were sent, with their images: after that their ids are a 404. Asks still waiting are never deleted.
Errors. {"error":{"code","message","hint","docUrl","requestId","issues"?,"ask"?}}. Every response has Logu-Request-Id. Retry 429 and 5xx with backoff; don't retry other 4xx.
| Code | Status | What to do |
|---|---|---|
bad_request |
400 | Fix the fields listed in issues and send the request again. |
approving_default |
400 | Use defaultOption: "decline" (fail closed) or leave it out; ask an Owner to create a rule for pre-approval. |
unknown_field |
400 | Remove or rename the fields listed in issues. Field names are camelCase. |
unauthorized |
401 | Send Authorization: Bearer lg_… with an active API key (create one in Logu → Agents). |
forbidden |
403 | Agents send asks, events and metrics; only a human Decider or Owner decides asks. |
workspace_suspended |
403 | Sign in at https://logu.dev to see the workspace, and contact Logu support to ask for a review. |
email_not_verified |
403 | Confirm your email with the link Logu sends (Settings → Account, or the invitation page), then retry. |
not_found |
404 | Check the path and the id. API keys only see their own workspace. |
method_not_allowed |
405 | Use one of the methods in the Allow header. |
conflict |
409 | Read the current state instead of retrying. |
idempotency_key_in_use |
409 | Retry in a moment with the same key to get its result. |
idempotency_key_reused |
422 | Use a new key for a different request; reuse a key only to retry the exact same request. |
rate_limited |
429 | Wait for Retry-After seconds, then retry. API key limits are per key, per minute. |
internal_error |
500 | Retry with backoff. If it persists, report the requestId. |
authorization_pending |
400 | Keep polling every interval seconds until the human approves or denies it, or it expires. |
slow_down |
400 | Wait 5 seconds longer between polls from now on, then poll again. |
expired_token |
400 | Start again: request a new device code (logu login). |
access_denied |
403 | Stop polling. Start again only if the human wants to connect this agent. |
plan_limit |
402 | An Owner can upgrade the workspace to Pro in Logu → Settings → Plan (on Pro, ask the Logu team to raise the quota); monthly counts reset on the 1st (UTC). |
ceiling_reached |
402 | Nothing was created, and an ask that wasn't created was not asked: don't proceed as if a human had answered. Tell your human; monthly counts reset on the 1st (UTC), and an operator can raise a ceiling for a workspace. Don't retry before then. |
overloaded |
503 | Retry after Retry-After seconds, with jitter. Nothing was lost: asks, events, metrics and decisions don't depend on the hub. |
service_unavailable |
503 | Retry with backoff; for a feature that isn't configured, ask the server's operator. |