Agent inboxes

Create an inbox

POST/v1/agent/inbox

Creates an inbox. Events routed to it wait until an agent pulls them.

Parameters

Body parameters7

namestringRequired

A unique name.

lease_seconds?integer

How long a picked-up event stays hidden, 30 to 3600. Default 300.

hold_seconds?integer

How long an event can wait before it expires. Default 7 days.

default_order?string

fifo (default), lifo or priority.

default_ack?string

manual (default) or pickup.

allowed_ack?string

Ack modes agents may ask for. Default manual,pickup.

priority_path?string

A body path read at ingest as the event's priority.

Returns

201The sample response is on the right.Errors return error and message; see Errors and limits.

POSTCreate an inbox

curl -X POST "https://api.getensue.com/v1/agent/inbox" \
  -H "authorization: Bearer $ENSUE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"billing-agent","lease_seconds":300}'

const res = await fetch("https://api.getensue.com/v1/agent/inbox", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.ENSUE_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "name": "billing-agent",
    "lease_seconds": 300
  }),
});
console.log(await res.json());

import os, requests

res = requests.post(
    "https://api.getensue.com/v1/agent/inbox",
    headers={"authorization": f"Bearer {os.environ['ENSUE_API_KEY']}"},
    json={
      "name": "billing-agent",
      "lease_seconds": 300
    },
)
print(res.json())

201Response

{
  "id": "dst_7q1c…",
  "name": "billing-agent",
  "type": "inbox",
  "status": "active",
  "created": 1762761600000,
  "lease_seconds": 300,
  "waiting": 3,
  "leased": 1,
  "oldest_at": 1762761700000,
  "wake": {
    "enabled": false
  }
}

{"id":"dst_7q1c…","name":"billing-agent","type":"inbox","status":"active","created":1762761600000,"lease_seconds":300,"waiting":3,"leased":1,"oldest_at":1762761700000,"wake":{"enabled":false}}