intentic
Download the app
Download the app
Connected systems

Needs

What an agent asked you to connect or provide before it can go on

On this page(10 sections)

An agent raises a need when a task stops on something only you can give: a capability, a credential, a change to its environment. These routes raise one and list an agent's own, list what is open for you, answer one or hand over its secret, withdraw one, and read or revoke the standing grants an answer left behind.

10 calls. Pick one to open it, or use the list on the right.

POST/needs/askAsk a person for something the task needs

Raises a need in the conversation the calling shell belongs to and holds the call up to `wait` seconds for an answer. Answers `met` when it is usable now (or already was), `open` when it is still waiting, and `refused` when nothing was raised or a person declined. An open need's answer reaches the conversation by itself.

What you send

FieldTypeWhere
askrequiredobjectbody
when kind is "capability"shapebody
entryrequiredThe catalog entry or a connected…stringbody
targetThe site, host or address it…stringbody
setSettings to fill in, or to…objectbody
reconnectIt is connected, but its credential…booleanbody
removeTake a connection away: the person…booleanbody
when kind is "secret"shapebody
namerequiredThe name it is stored under,…stringbody
whereHow it will be used: the…stringbody
linkWhere a person gets one, shown…stringbody
hintWhat a valid one looks like,…stringbody
replaceOne is stored under this name…booleanbody
multilineA value with lines (a key…booleanbody
when kind is "grant"shapebody
subjectrequiredA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"body
whatrequiredstringbody
when kind is "release"shapebody
subjectrequiredstringbody
when kind is "environment"shapebody
toolrequiredstringbody
stepsrequiredstringbody
when kind is "automation"shapebody
automationrequiredobjectbody
idrequiredThe automation's idstringbody
triggerrequiredWhat sets it off: a schedule,…objectbody
guardA command run before the wake…stringbody
sourceA ready-made check instead of a…objectbody
fireOnFire on every passing check, or…"pass" | "change"body
untilSwitch it off the first time…"first-fire"body
expiresAtWhen it gives up, in millisecondsintegerbody
targetWhat a passing check sets off:…objectbody
noteOne line on what it watches…stringbody
promptrequiredWhat the woken agent is toldstringbody
webchatSettings for the public chat widget,…objectbody
issuesSettings for the bug reporter, for…objectbody
allowedToolsNarrow the woken turn to these…string[]body
modelsWhich models this automation may run…object[]body
accountWhich account pays for itstringbody
actsAsWhich role it speaks asstringbody
runAsWhich service it acts as: whose…stringbody
sendersWho may talk to it, and…objectbody
requireApprovalHold every fire for a person…booleanbody
holdForSecondsHold each fire this long before…numberbody
choreThis automation is a maintenance job,…booleanbody
groupWhich shelf of the Automations panel…stringbody
enabledrequiredWhether it fires at allbooleanbody
createdByWho made it, as the sandbox…stringbody
when kind is "instruction"shapebody
filerequiredThe AGENTS.md, relative to the workspace…stringbody
textrequiredThe rule, as it should read…stringbody
whystringbody
waitSeconds to hold the call for…integerbody

What comes back

FieldType
state"met" | "open" | "refused"
messageThe sentence the CLI prints, written…string
needobject
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
replacesAn automation of this id already…boolean
firstCheckobject
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
codeA refusal's type, for a script…string
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/ask" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"ask":{"kind":"capability","entry":"…","target":"…","set":{"src/app.ts":"…","README.md":"…"},"reconnect":true,"remove":true},"why":"…","wait":0}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.ask({
  "ask": {
    "kind": "capability",
    "entry": "…",
    "target": "…",
    "set": {
      "src/app.ts": "…",
      "README.md": "…"
    },
    "reconnect": true,
    "remove": true
  },
  "why": "…",
  "wait": 0
});
GET/needs/mineThis conversation's needs

Every need the calling shell's conversation raised, newest first, open or answered.

What you send

Nothing. Call it as it is.

What comes back

FieldType
needsNewest firstobject[]
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
replacesAn automation of this id already…boolean
firstCheckobject
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl "$SANDBOX/needs/mine" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.mine();
POST/needs/{id}/withdrawWithdraw a need

Closes one of this conversation's open needs because the task no longer needs it. Its card says so.

What you send

FieldTypeWhere
idrequiredWhich needstringaddress

What comes back

FieldType
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
idThe role's id, or a built-in'sstring
labelIts name on screenstring
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
idThe automation's idstring
triggerWhat sets it off: a schedule,…object
guardA command run before the wake…string
sourceA ready-made check instead of a…object
fireOnFire on every passing check, or…"pass" | "change"
untilSwitch it off the first time…"first-fire"
expiresAtWhen it gives up, in millisecondsinteger
targetWhat a passing check sets off:…object
noteOne line on what it watches…string
promptWhat the woken agent is toldstring
webchatSettings for the public chat widget,…object
issuesSettings for the bug reporter, for…object
allowedToolsNarrow the woken turn to these…string[]
modelsWhich models this automation may run…object[]
accountWhich account pays for itstring
actsAsWhich role it speaks asstring
runAsWhich service it acts as: whose…string
sendersWho may talk to it, and…object
requireApprovalHold every fire for a person…boolean
holdForSecondsHold each fire this long before…number
choreThis automation is a maintenance job,…boolean
groupWhich shelf of the Automations panel…string
enabledWhether it fires at allboolean
createdByWho made it, as the sandbox…string
replacesAn automation of this id already…boolean
firstCheckobject
passWhether the check passes today, which…boolean
sawWhat it saw, or what it…string
atWhen it ran, in millisecondsnumber
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
idWhich setting or behaviour (POWER_FINDING), as…string
powerThe power source it applies to:…"ac" | "dc"
afterSecondsFor a timeout: how long without…integer
actionFor the lid: what closing it…string
windowFor an update restart: the local…object
plansWindows: the power plans that hold…string[]
fixableWhether the agent's `power-stay-on` op changes…boolean
commandWhere the agent cannot change it:…string
textWhat it does now, in the…string
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/a1b2c3d4/withdraw" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.withdraw({
  "id": "a1b2c3d4"
});
POST/needs/{id}/doneClose a need as met, on the agent's word

Closes one of this conversation's open needs as met, with what showed the agent it works: only a need no check of the daemon's can see met (a credential reported refused while its connection still probes fine), once a person said in the chat it was fixed. Any other need is refused: the daemon closes those itself.

What you send

FieldTypeWhere
idrequiredWhich needstringaddress
howrequiredWhat showed the agent it works…stringbody

What comes back

FieldType
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
idThe role's id, or a built-in'sstring
labelIts name on screenstring
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
idThe automation's idstring
triggerWhat sets it off: a schedule,…object
guardA command run before the wake…string
sourceA ready-made check instead of a…object
fireOnFire on every passing check, or…"pass" | "change"
untilSwitch it off the first time…"first-fire"
expiresAtWhen it gives up, in millisecondsinteger
targetWhat a passing check sets off:…object
noteOne line on what it watches…string
promptWhat the woken agent is toldstring
webchatSettings for the public chat widget,…object
issuesSettings for the bug reporter, for…object
allowedToolsNarrow the woken turn to these…string[]
modelsWhich models this automation may run…object[]
accountWhich account pays for itstring
actsAsWhich role it speaks asstring
runAsWhich service it acts as: whose…string
sendersWho may talk to it, and…object
requireApprovalHold every fire for a person…boolean
holdForSecondsHold each fire this long before…number
choreThis automation is a maintenance job,…boolean
groupWhich shelf of the Automations panel…string
enabledWhether it fires at allboolean
createdByWho made it, as the sandbox…string
replacesAn automation of this id already…boolean
firstCheckobject
passWhether the check passes today, which…boolean
sawWhat it saw, or what it…string
atWhen it ran, in millisecondsnumber
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
idWhich setting or behaviour (POWER_FINDING), as…string
powerThe power source it applies to:…"ac" | "dc"
afterSecondsFor a timeout: how long without…integer
actionFor the lid: what closing it…string
windowFor an update restart: the local…object
plansWindows: the power plans that hold…string[]
fixableWhether the agent's `power-stay-on` op changes…boolean
commandWhere the agent cannot change it:…string
textWhat it does now, in the…string
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/a1b2c3d4/done" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"how":"…"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.done({
  "id": "a1b2c3d4",
  "how": "…"
});
GET/needsWhat agents are waiting on people for

Needs across the sandbox, or one conversation's, newest first. Never a secret's value.

What you send

FieldTypeWhere
conversationIdOne conversation's needsstringquery
openOnly the ones still waitingbooleanquery

What comes back

FieldType
needsNewest firstobject[]
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
replacesAn automation of this id already…boolean
firstCheckobject
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl "$SANDBOX/needs" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.list();
POST/needs/{id}/answerAnswer a need

Declines it, or says yes the way its card offered: accept a connection being set up, apply a change, grant for this conversation or the role, release a gated credential, approve an environment proposal. A release is refused from anyone the gate does not name.

What you send

FieldTypeWhere
idrequiredWhich needstringaddress
answerrequiredobjectbody
when kind is "decline"shapebody
noteWhy not, passed to the agentstringbody
when kind is "accept"shapebody
when kind is "apply"shapebody
when kind is "grant"shapebody
rolerequiredWhich of the need's roles the…stringbody
when kind is "release"shapebody
when kind is "approve"shapebody

What comes back

FieldType
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
idThe role's id, or a built-in'sstring
labelIts name on screenstring
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
idThe automation's idstring
triggerWhat sets it off: a schedule,…object
guardA command run before the wake…string
sourceA ready-made check instead of a…object
fireOnFire on every passing check, or…"pass" | "change"
untilSwitch it off the first time…"first-fire"
expiresAtWhen it gives up, in millisecondsinteger
targetWhat a passing check sets off:…object
noteOne line on what it watches…string
promptWhat the woken agent is toldstring
webchatSettings for the public chat widget,…object
issuesSettings for the bug reporter, for…object
allowedToolsNarrow the woken turn to these…string[]
modelsWhich models this automation may run…object[]
accountWhich account pays for itstring
actsAsWhich role it speaks asstring
runAsWhich service it acts as: whose…string
sendersWho may talk to it, and…object
requireApprovalHold every fire for a person…boolean
holdForSecondsHold each fire this long before…number
choreThis automation is a maintenance job,…boolean
groupWhich shelf of the Automations panel…string
enabledWhether it fires at allboolean
createdByWho made it, as the sandbox…string
replacesAn automation of this id already…boolean
firstCheckobject
passWhether the check passes today, which…boolean
sawWhat it saw, or what it…string
atWhen it ran, in millisecondsnumber
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
idWhich setting or behaviour (POWER_FINDING), as…string
powerThe power source it applies to:…"ac" | "dc"
afterSecondsFor a timeout: how long without…integer
actionFor the lid: what closing it…string
windowFor an update restart: the local…object
plansWindows: the power plans that hold…string[]
fixableWhether the agent's `power-stay-on` op changes…boolean
commandWhere the agent cannot change it:…string
textWhat it does now, in the…string
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/a1b2c3d4/answer" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"answer":{"kind":"decline","note":"…"}}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.answer({
  "id": "a1b2c3d4",
  "answer": {
    "kind": "decline",
    "note": "…"
  }
});
POST/needs/{id}/releaseRelease a gated credential, or decline

A release need's answer, from one of the approvers its gate names, whatever their tier: release the credential to the conversation that asked, or decline. Any other need is answered through /needs/{id}/answer.

What you send

FieldTypeWhere
idrequiredWhich needstringaddress
answerrequiredRelease the credential to the conversation,…"release" | "decline"body

What comes back

FieldType
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
idThe role's id, or a built-in'sstring
labelIts name on screenstring
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
idThe automation's idstring
triggerWhat sets it off: a schedule,…object
guardA command run before the wake…string
sourceA ready-made check instead of a…object
fireOnFire on every passing check, or…"pass" | "change"
untilSwitch it off the first time…"first-fire"
expiresAtWhen it gives up, in millisecondsinteger
targetWhat a passing check sets off:…object
noteOne line on what it watches…string
promptWhat the woken agent is toldstring
webchatSettings for the public chat widget,…object
issuesSettings for the bug reporter, for…object
allowedToolsNarrow the woken turn to these…string[]
modelsWhich models this automation may run…object[]
accountWhich account pays for itstring
actsAsWhich role it speaks asstring
runAsWhich service it acts as: whose…string
sendersWho may talk to it, and…object
requireApprovalHold every fire for a person…boolean
holdForSecondsHold each fire this long before…number
choreThis automation is a maintenance job,…boolean
groupWhich shelf of the Automations panel…string
enabledWhether it fires at allboolean
createdByWho made it, as the sandbox…string
replacesAn automation of this id already…boolean
firstCheckobject
passWhether the check passes today, which…boolean
sawWhat it saw, or what it…string
atWhen it ran, in millisecondsnumber
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
idWhich setting or behaviour (POWER_FINDING), as…string
powerThe power source it applies to:…"ac" | "dc"
afterSecondsFor a timeout: how long without…integer
actionFor the lid: what closing it…string
windowFor an update restart: the local…object
plansWindows: the power plans that hold…string[]
fixableWhether the agent's `power-stay-on` op changes…boolean
commandWhere the agent cannot change it:…string
textWhat it does now, in the…string
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/a1b2c3d4/release" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"answer":"release"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.release({
  "id": "a1b2c3d4",
  "answer": "release"
});
POST/needs/{id}/secretGive a secret a need asked for

Stores the value under the name the need asked for and meets it. The value goes to the sandbox's secret store and nowhere else: not the answer, not the transcript, not a log.

What you send

FieldTypeWhere
idrequiredWhich needstringaddress
valuerequiredThe secret's valuestringbody
keepOnKeep it in the keyring on…objectbody
devicerequiredWhich computer's keyring keeps it, by…stringbody
moderequiredHow that keyring answers this sandbox…"each-use" | "while-here" | "copy"body

What comes back

FieldType
idThe need's handle, the one `needs…string
conversationIdThe conversation that asked, and the…string
subjectWhat exactly is asked forobject
when kind is "capability"shape
entryThe catalog entry, as the catalog…string
nameWhat the catalog calls it, never…string
modeConnect something new, give a connected…"connect" | "reconnect" | "change" | "remove"
instanceThe connection a reconnect, a change…string
targetThe site, host or address the…string
prefillSettings the agent could fill in…object
changesFor a change: each setting and…object
reasonThe daemon's own sentence on why…string
reportedThe agent reported the credential refused…boolean
when kind is "secret"shape
nameThe name it is stored under,…string
whereHow it will be used: the…string
linkWhere a person gets one, shown…string
hintWhat a valid one looks like,…string
replaceOne is stored under this name…boolean
multilineA value with lines (a key…boolean
when kind is "grant"shape
subjectA connected capability the conversation's role…"capability" | "folder" | "shelf" | "site"
whatThe capability's id, the folder, or…string
labelWhat it is, in the daemon's…string
roleThe role that withholds it, when…string
rolesThe roles whose access allows it,…object[]
idThe role's id, or a built-in'sstring
labelIts name on screenstring
scopeHow far the yes went, on…"conversation" | "persona"
when kind is "release"shape
subjectThe gated account or connectorstring
approversWho may release itstring[]
when kind is "environment"shape
toolWhat the steps install, the name…string
stepsThe Dockerfile steps proposed for the…string
approvedHashThe overlay these steps were approved…string
when kind is "automation"shape
automationThe automation as it would be…object
idThe automation's idstring
triggerWhat sets it off: a schedule,…object
guardA command run before the wake…string
sourceA ready-made check instead of a…object
fireOnFire on every passing check, or…"pass" | "change"
untilSwitch it off the first time…"first-fire"
expiresAtWhen it gives up, in millisecondsinteger
targetWhat a passing check sets off:…object
noteOne line on what it watches…string
promptWhat the woken agent is toldstring
webchatSettings for the public chat widget,…object
issuesSettings for the bug reporter, for…object
allowedToolsNarrow the woken turn to these…string[]
modelsWhich models this automation may run…object[]
accountWhich account pays for itstring
actsAsWhich role it speaks asstring
runAsWhich service it acts as: whose…string
sendersWho may talk to it, and…object
requireApprovalHold every fire for a person…boolean
holdForSecondsHold each fire this long before…number
choreThis automation is a maintenance job,…boolean
groupWhich shelf of the Automations panel…string
enabledWhether it fires at allboolean
createdByWho made it, as the sandbox…string
replacesAn automation of this id already…boolean
firstCheckobject
passWhether the check passes today, which…boolean
sawWhat it saw, or what it…string
atWhen it ran, in millisecondsnumber
when kind is "instruction"shape
fileThe AGENTS.md it goes into, relative…string
textThe rule as it would be…string
diffThe change as a unified diff…string
createsThe file does not exist yet:…boolean
when kind is "host-power"shape
deviceThe connected computer this sandbox runs…string
findingsWhat its OS would do to…object[]
idWhich setting or behaviour (POWER_FINDING), as…string
powerThe power source it applies to:…"ac" | "dc"
afterSecondsFor a timeout: how long without…integer
actionFor the lid: what closing it…string
windowFor an update restart: the local…object
plansWindows: the power plans that hold…string[]
fixableWhether the agent's `power-stay-on` op changes…boolean
commandWhere the agent cannot change it:…string
textWhat it does now, in the…string
dueAtWhen the booked work that raised…number
titleThe one line it leads with,…string
whyThe agent's case for it, and…string
statusWhere it stands: open (waiting on…"open" | "working" | "met" | "declined" … (5)
createdAtWhen it was raised, in millisecondsnumber
updatedAtWhen it last moved, in millisecondsnumber
answeredByWho answered it, as the sandbox…string
byAgentThe agent closed it as met…boolean
outcomeHow it ended, in the daemon's…string
toldHow the agent heard the outcome,…"call" | "turn" | "queued"
unattendedRaised by a turn nobody was…boolean
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/a1b2c3d4/secret" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"value":"…","keepOn":{"device":"…","mode":"each-use"}}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.provideSecret({
  "id": "a1b2c3d4",
  "value": "…",
  "keepOn": {
    "device": "…",
    "mode": "each-use"
  }
});
GET/needs/grantsThe yeses still standing

What people allowed conversations beyond their role or area, and the gated credentials released to them, by conversation; and, apart from them, the yeses that name no conversation: command policy lines allowed with Always, approved hook sets, approved workspace extensions. Names only, never a value.

What you send

Nothing. Call it as it is.

What comes back

FieldType
conversationsobject[]
conversationIdstring
installsWhether its own dependency installs run…boolean
secretsSecrets it may send past their…string[]
everythingWhether every request an allow-once could…boolean
autoApproveWhether it and its subagents are…boolean
rulesCredential gateway rules that no longer…object[]
capabilityThe capability whose rule asked, by…string
ruleThe rule's own identity (its content),…string
saidThe request in a person's words,…string
byWho last allowed one of thosestring
updatedAtWhen one of those last changed,…number
releasesGated credentials released to it, until…object[]
subjectstring
approvedBystring
atnumber
ownerWideYeses that name no conversation: command…object[]
when kind is "command-policy"shape
lineThe policy line the judge reads,…string
atWhen it was allowed, in millisecondsnumber
byWho allowed it, off the verified…string
when kind is "hook-set"shape
digestThe set's fingerprint, what taking it…string
hooksEach hook in the set in…string[]
atWhen it was approved, in millisecondsnumber
when kind is "extension"shape
idThe extension, by its publisher.name idstring
powersWhat it was approved to do,…string[]
atWhen it was approved, in millisecondsnumber
unreadableKinds of owner-wide yes whose record…"command-policy" | "hook-set" | "extension"[]
Try itanswered in this tab
curl
curl "$SANDBOX/needs/grants" \
  -H "x-intentic-control: $INTENTIC_TOKEN"
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.grants();
POST/needs/grants/revokeTake a yes back

Takes back one grant or one release of a conversation, or one owner-wide yes (a policy line, a hook set, an extension). A conversation's next turn runs without it; a turn already running keeps what it mounted.

What you send

FieldTypeWhere
conversationIdrequiredstringbody
kindrequiredWhich kind of yes: a credential's…"release" | "install" | "secret" | "everything" … (6)body
whatrequiredThe released credential or secret it…stringbody
capabilityFor a rule, the capability whose…stringbody

What comes back

FieldType
okAlways truetrue
Try itanswered in this tab
curl
curl -X POST "$SANDBOX/needs/grants/revoke" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"conversationId":"nightly-changelog","kind":"release","what":"2026-08-21T09:14:02.000Z","capability":"…"}'
TypeScript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.revokeGrant({
  "conversationId": "nightly-changelog",
  "kind": "release",
  "what": "2026-08-21T09:14:02.000Z",
  "capability": "…"
});

Type to search every page, in the docs and the API reference.