Curiosity API

The curiosity queue is a list of standing questions that Puck re-investigates on a schedule. Each item is a natural-language query paired with a scope selector, a depth level, and a recurrence interval. When the scheduled time arrives the brain triggers a fresh investigation automatically, exactly as if you had called POST /v1/investigations manually.

Curiosity items are useful for ambient monitoring: “are any new browser extensions appearing on engineering endpoints?”, “did the list of outbound destinations change since yesterday?”. Each completed run links back to the curiosity item that triggered it so you can track trends over time.

---

GET /v1/curiosity

List all curiosity queue items for the account. Results are sorted by next_run_at ascending (soonest-due first) and are cursor-paginated.

Scope required: curiosity:read

curl https://puck.acme.com/v1/curiosity \
  -H "Authorization: Bearer $PUCK_API_KEY"

const res = await fetch("https://puck.acme.com/v1/curiosity", {
  headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` },
});
const { items, next_cursor } = await res.json();

---

POST /v1/curiosity

Create a new curiosity queue item. The brain schedules the first run immediately (or at first_run_at if specified) and re-queues it after each completed run according to the interval.

Scope required: curiosity:write

Field	Required	Description
query	Yes	Natural-language investigation question
interval	Yes	Recurrence interval, e.g. "24h", "7d", "1h"
scope	No	Agent selector (same shape as POST /v1/investigations)
depth	No	quick, standard, or deep (default standard)
first_run_at	No	ISO-8601 timestamp for the first run (default: immediately)
active	No	Whether scheduled (default true)

curl https://puck.acme.com/v1/curiosity \
  -H "Authorization: Bearer $PUCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "check for new browser extensions on engineering laptops",
    "interval": "24h",
    "scope": { "type": "selector", "filter": { "tags": { "team": "engineering" } } },
    "depth": "quick"
  }'

const res = await fetch("https://puck.acme.com/v1/curiosity", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PUCK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "check for new browser extensions on engineering laptops",
    interval: "24h",
    depth: "quick",
  }),
});
const { id, next_run_at } = await res.json();

---

PATCH /v1/curiosity/{id}

Update an existing curiosity item. All fields are optional. Use active: false to pause an item without deleting it.

Scope required: curiosity:write

curl -X PATCH "https://puck.acme.com/v1/curiosity/cur_01hx" \
  -H "Authorization: Bearer $PUCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval": "12h", "active": false }'

---

DELETE /v1/curiosity/{id}

Permanently delete a curiosity item. Any investigation already triggered by this item is not affected. Returns 204 No Content on success.

Scope required: curiosity:write

curl -X DELETE "https://puck.acme.com/v1/curiosity/cur_01hx" \
  -H "Authorization: Bearer $PUCK_API_KEY"