Rules · createRule

Create a rule

POST /v1/rules

An Owner's decision made in advance, narrow by design: asks from one agent (agentId) in one project (projectId), with exactly title when it's set, that offer optionId are decided with that option as soon as they're sent, by this Owner (decidedVia: "rule", decidedBy: the Owner, ruleId). Optionally until expiresAt and for maxUses asks. Only asks sent after it's created; test asks too. A rule decides nothing once its creator is no longer an Owner. Owners only, with a session: API keys can never create rules. Up to 100 per workspace.

Who may call it: humans: Owners and up
Server: https://api.logu.dev

Parameters#

Name	In	Type	Required	Description
`Logu-Workspace`	header	`string`	optional	Humans only: the workspace to act in (default: your personal workspace). Agents always act in their API key's workspace. · e.g. `wsp_01K7D7Y8Z0B2D4F6H8K0M2P4R6`

Request body#

Content type application/json (required).

Field	Type	Required	Notes
`projectId`	`string`	required	1–∞ chars
`agentId`	`string`	required	1–∞ chars
`title`	`string`	optional	1–200 chars
`optionId`	`string`	required	1–64 chars · pattern `^[a-z0-9][a-z0-9._-]*$`
`expiresAt`	`string`	optional	date-time
`maxUses`	`integer`	optional	1–10000

{
  "projectId": "prj_01K7D9A1C3E5G7J9L1N3Q5S7U9",
  "agentId": "agt_01K7D8F2H4K6M8P0R2T4V6X8Z0",
  "title": "Deploy v1.4 to staging?",
  "optionId": "approve",
  "expiresAt": "2026-11-12T14:00:00.000Z",
  "maxUses": 20
}

Example#

curl -s -X POST "https://api.logu.dev/v1/rules" \
  -H "Authorization: Bearer $LOGU_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"prj_01K7D9A1C3E5G7J9L1N3Q5S7U9","agentId":"agt_01K7D8F2H4K6M8P0R2T4V6X8Z0","title":"Deploy v1.4 to staging?","optionId":"approve","expiresAt":"2026-11-12T14:00:00.000Z","maxUses":20}'

Responses#

201

The rule.

{
  "id": "rul_01K7DC7G9J1L3N5Q7S9U1W3Y5A",
  "projectId": "prj_01K7D9A1C3E5G7J9L1N3Q5S7U9",
  "project": "shop",
  "agent": {
    "id": "agt_01K7D8F2H4K6M8P0R2T4V6X8Z0",
    "name": "deploy-bot"
  },
  "title": "Deploy v1.4 to staging?",
  "optionId": "approve",
  "expiresAt": "2026-11-12T14:00:00.000Z",
  "maxUses": 20,
  "uses": 3,
  "lastUsedAt": "2026-10-12T14:05:42.000Z",
  "status": "active",
  "createdBy": {
    "id": "Xq3bY7tLmN2pR8sV",
    "name": "Ana"
  },
  "createdAt": "2026-10-12T14:03:11.000Z"
}

Response fields

Field	Type	Required	Notes
`id`	`string`	required
`projectId`	`string`	required
`project`	`string`	required
`agent`	`AgentRef`	required
`agent.id`	`string`	required
`agent.name`	`string`	required
`title`	`string \| null`	required
`optionId`	`string`	required
`expiresAt`	`string \| null`	required	date-time
`maxUses`	`integer \| null`	required
`uses`	`integer`	required
`lastUsedAt`	`string \| null`	required	date-time
`status`	`"active" \| "expired" \| "used_up" \| "inactive"`	required
`createdBy`	`MemberRef \| null`	required
`createdBy.id`	`string`	required
`createdBy.name`	`string`	required
`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.
403	`forbidden`	The caller is authenticated but may not do this (wrong role, or an API key on a human-only endpoint).
404	`not_found`	No such route, or the resource doesn't exist in your workspace.
409	`conflict`	The resource isn't in a state that allows this: an ask that is no longer waiting (`ask` has its current state), an invitation no longer pending, the last Owner.
500	`internal_error`	Something went wrong on Logu's side.