Ciresk Docs
API reference

Needs

An agent tells its person it is blocked on them; the person replies or dismisses it.

GET/v1/dev/sessions/{session_id}/needs

List needs

The session's needs, oldest first - the open ones by default; with number, one need and its reply.

Owner and members. An agent reads the person's answer here: number names the need it raised, whatever its state, and the answer carries state answered with reply, dismissed, or cleared (the session ended).

Permission: dev:sessions.read

Parameters

NameTypeRequiredDescription
session_idpathstringRequiredThe session's ID.
statequerystringOptional
numberqueryintegerOptional
cursorquerystringOptional
limitqueryintegerOptional

Response200 OK

dataarray of objectsRequired
data[].actorstringRequired
who raised it as a person reads it: Claude Code · Lucas; Ciresk dev for expiring and budget
data[].agentstring or null
the agent identity and harness, as the audit names it
data[].kindstringRequired
One of question, approval, failing_check, expiring, budget
data[].linkstring or null
data[].numberintegerRequired
the seq of its need.raised event
data[].personstringRequired
the person it is addressed to, user:<id>
data[].raised_atstring (date-time)Required
data[].raised_bystringRequired
the requester's subject: agent:<id>, user:<id>, a service, or dev-api
data[].replystring or null
data[].resolved_atstring (date-time) or null
data[].resolved_bystring or null
data[].session_idstringRequired
data[].statestringRequired
cleared: the session ended while it was openOne of open, answered, dismissed, cleared
data[].textstringRequired
has_morebooleanRequired
next_cursorstring or null
curl "$CIRESK_API/v1/dev/sessions/devs_0166ba8e973a3df1b173b30df1cb8f2f/needs" \
  -H "Authorization: Bearer $CIRESK_KEY"
POST/v1/dev/sessions/{session_id}/needs

Raise a need

Tell the person the agent is blocked on them - a question, an approval, a failing check it cannot fix.

"Needs you". The owner or a member with use, or their agent, raises it; it is addressed to the caller's accountable person (an agent's owner; a service's goes to the session's owner) and names its actor as a person reads it, "Claude Code · Lucas", from the Ciresk-Agent header and the directory. Appends an inbound need.raised event, whose seq is the need's number, and counts it in the session's needs_open. text is one line of at most 280 characters (control characters become spaces); link is one url or reference, e.g. exec:<id> or a CI job url. On by default with no switch to turn it off; at most 10 raises per session per hour (429 rate_limited with Retry-After). The same kind and text while that need is open returns it (200) instead of raising it twice. dev raises kind expiring itself, lifetime_warning_secs before the session's max lifetime, and kind budget when the session's budget will stop it (Budget); neither counts towards the limit. 409 session_not_running on an ended session.

Permission: dev:sessions.attach

Parameters

NameTypeRequiredDescription
session_idpathstringRequiredThe session's ID.

Request body

kindstringRequired
One of question, approval, failing_check
linkstring
one url or reference without spaces: exec:<id>, evidence:<path>, a CI job url
textstringRequired
one line the person reads at a glance; control characters become spaces

Response200 OK

actorstringRequired
who raised it as a person reads it: Claude Code · Lucas; Ciresk dev for expiring and budget
agentstring or null
the agent identity and harness, as the audit names it
kindstringRequired
One of question, approval, failing_check, expiring, budget
linkstring or null
numberintegerRequired
the seq of its need.raised event
personstringRequired
the person it is addressed to, user:<id>
raised_atstring (date-time)Required
raised_bystringRequired
the requester's subject: agent:<id>, user:<id>, a service, or dev-api
replystring or null
resolved_atstring (date-time) or null
resolved_bystring or null
session_idstringRequired
statestringRequired
cleared: the session ended while it was openOne of open, answered, dismissed, cleared
textstringRequired

Errors

curl -X POST "$CIRESK_API/v1/dev/sessions/devs_0166ba8e973a3df1b173b30df1cb8f2f/needs" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "question",
    "link": "https://ci.eu.ciresk.com/jobs/job_0109badfc220cd056b2c0e862ac73d40",
    "text": "Go ahead."
  }'
POST/v1/dev/sessions/{session_id}/needs/{number}/dismiss

Dismiss a need

Close a need unanswered - the person, the session's owner, or the person's agent withdrawing it.

The person the need is addressed to or the session's owner, or an agent acting for them, else 403 not_allowed. Appends an inbound need.dismissed event. Dismissing a dismissed need returns it.

Permission: dev:sessions.attach

Parameters

NameTypeRequiredDescription
session_idpathstringRequiredThe session's ID.
numberpathintegerRequiredthe need's number, the seq of its need.raised event

Response200 OK

actorstringRequired
who raised it as a person reads it: Claude Code · Lucas; Ciresk dev for expiring and budget
agentstring or null
the agent identity and harness, as the audit names it
kindstringRequired
One of question, approval, failing_check, expiring, budget
linkstring or null
numberintegerRequired
the seq of its need.raised event
personstringRequired
the person it is addressed to, user:<id>
raised_atstring (date-time)Required
raised_bystringRequired
the requester's subject: agent:<id>, user:<id>, a service, or dev-api
replystring or null
resolved_atstring (date-time) or null
resolved_bystring or null
session_idstringRequired
statestringRequired
cleared: the session ended while it was openOne of open, answered, dismissed, cleared
textstringRequired

Errors

curl -X POST "$CIRESK_API/v1/dev/sessions/devs_0166ba8e973a3df1b173b30df1cb8f2f/needs/d5189743-c854-4635-9d15-741eb6923d0a/dismiss" \
  -H "Authorization: Bearer $CIRESK_KEY"
POST/v1/dev/sessions/{session_id}/needs/{number}/reply

Reply to a need

The person answers a need; the agent reads the reply through dev.sessions.needs.list.

A person only, the one the need is addressed to or the session's owner, else 403 not_allowed; an agent never answers a need. Appends an inbound need.answered event with the reply (at most 2,000 characters, lines kept). The same reply again returns the answered need; another one is 409 need_not_open.

Permission: dev:sessions.attach

Parameters

NameTypeRequiredDescription
session_idpathstringRequiredThe session's ID.
numberpathintegerRequiredthe need's number, the seq of its need.raised event

Request body

replystringRequired

Response200 OK

actorstringRequired
who raised it as a person reads it: Claude Code · Lucas; Ciresk dev for expiring and budget
agentstring or null
the agent identity and harness, as the audit names it
kindstringRequired
One of question, approval, failing_check, expiring, budget
linkstring or null
numberintegerRequired
the seq of its need.raised event
personstringRequired
the person it is addressed to, user:<id>
raised_atstring (date-time)Required
raised_bystringRequired
the requester's subject: agent:<id>, user:<id>, a service, or dev-api
replystring or null
resolved_atstring (date-time) or null
resolved_bystring or null
session_idstringRequired
statestringRequired
cleared: the session ended while it was openOne of open, answered, dismissed, cleared
textstringRequired

Errors

curl -X POST "$CIRESK_API/v1/dev/sessions/devs_0166ba8e973a3df1b173b30df1cb8f2f/needs/d5189743-c854-4635-9d15-741eb6923d0a/reply" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reply": "Go ahead."
  }'