Connected systems

Needs

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

On this page(8 sections)

Ask a person for something the task needs
This conversation's needs
Withdraw a need
What agents are waiting on people for
Answer a need
Give a secret a need asked for
The yeses still standing
Take a yes back

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.

8 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

Field	Type	Where
`ask`required	object	body
`when kind is "capability"`	shape	body
`entry`requiredThe catalog entry or a connected…	string	body
`target`The site, host or address it…	string	body
`set`Settings to fill in, or to…	object	body
`reconnect`It is connected, but its credential…	boolean	body
`when kind is "secret"`	shape	body
`name`requiredThe name it is stored under,…	string	body
`where`How it will be used: the…	string	body
`link`Where a person gets one, shown…	string	body
`hint`What a valid one looks like,…	string	body
`replace`One is stored under this name…	boolean	body
`when kind is "grant"`	shape	body
`subject`requiredA connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"	body
`what`required	string	body
`when kind is "release"`	shape	body
`subject`required	string	body
`when kind is "environment"`	shape	body
`tool`required	string	body
`steps`required	string	body
`why`	string	body
`wait`Seconds to hold the call for…	integer	body

What comes back

Field	Type
`state`	"met" \| "open" \| "refused"
`message`The sentence the CLI prints, written…	string
`need`	object
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised by a turn nobody was…	boolean
`code`A 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},"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
  },
  "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

Field	Type
`needs`Newest first	object[]
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised 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

Field	Type	Where
`id`requiredWhich need	string	address

What comes back

Field	Type
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised 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"
});

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

Field	Type	Where
`conversationId`One conversation's needs	string	query
`open`Only the ones still waiting	boolean	query

What comes back

Field	Type
`needs`Newest first	object[]
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised 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 persona, release a gated credential, approve an environment proposal. A release is refused from anyone the gate does not name.

What you send

Field	Type	Where
`id`requiredWhich need	string	address
`answer`required	object	body
`when kind is "decline"`	shape	body
`note`Why not, passed to the agent	string	body
`when kind is "accept"`	shape	body
`when kind is "apply"`	shape	body
`when kind is "grant"`	shape	body
`scope`requiredHow far a yes goes: this…	"conversation" \| "persona"	body
`when kind is "release"`	shape	body
`when kind is "approve"`	shape	body

What comes back

Field	Type
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised 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}/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

Field	Type	Where
`id`requiredWhich need	string	address
`value`requiredThe secret's value	string	body

What comes back

Field	Type
`id`The need's handle, the one `needs…	string
`conversationId`The conversation that asked, and the…	string
`subject`What exactly is asked for	object
`when kind is "capability"`	shape
`entry`The catalog entry, as the catalog…	string
`name`What the catalog calls it, never…	string
`mode`Connect something new, give a connected…	"connect" \| "reconnect" \| "change"
`instance`The connection a reconnect or a…	string
`target`The site, host or address the…	string
`prefill`Settings the agent could fill in…	object
`changes`For a change: each setting and…	object
`reason`The daemon's own sentence on why…	string
`reported`The agent reported the credential refused…	boolean
`when kind is "secret"`	shape
`name`The name it is stored under,…	string
`where`How it will be used: the…	string
`link`Where a person gets one, shown…	string
`hint`What a valid one looks like,…	string
`replace`One is stored under this name…	boolean
`when kind is "grant"`	shape
`subject`A connected capability the persona leaves…	"capability" \| "folder" \| "shelf" \| "site"
`what`The capability's id, the folder, or…	string
`label`What it is, in the daemon's…	string
`persona`The persona that withholds it, when…	string
`scope`How far the yes went, once…	"conversation" \| "persona"
`when kind is "release"`	shape
`subject`The gated account or connector	string
`approvers`Who may release it	string[]
`when kind is "environment"`	shape
`tool`What the steps install, the name…	string
`steps`The Dockerfile steps proposed for the…	string
`approvedHash`The overlay these steps were approved…	string
`title`The one line it leads with,…	string
`why`The agent's case for it, and…	string
`status`Where it stands: open (waiting on…	"open" \| "working" \| "met" \| "declined" … (5)
`createdAt`When it was raised, in milliseconds	number
`updatedAt`When it last moved, in milliseconds	number
`answeredBy`Who answered it, as the sandbox…	string
`outcome`How it ended, in the daemon's…	string
`told`How the agent heard the outcome,…	"call" \| "turn" \| "queued"
`unattended`Raised 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":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.needs.provideSecret({
  "id": "a1b2c3d4",
  "value": "…"
});

GET/needs/grantsThe yeses still standing

What people allowed conversations beyond their persona or area, and the gated credentials released to them, by conversation. Names only, never a value.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`conversations`	object[]
`conversationId`	string
`capabilities`Connected capabilities allowed although its persona…	string[]
`folders`Workspace folders its file tools may…	string[]
`shelves`Shelves of tools opened for it	"files" \| "shell" \| "code" \| "web" … (7)[]
`installs`Whether its own dependency installs run…	boolean
`secrets`Secrets it may send past their…	string[]
`everything`Whether every request an allow-once could…	boolean
`by`Who last allowed one of those	string
`updatedAt`When one of those last changed,…	number
`releases`Gated credentials released to it, until…	object[]
`subject`	string
`approvedBy`	string
`at`	number

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. The conversation's next turn runs without it; a turn already running keeps what it mounted.

What you send

Field	Type	Where
`conversationId`required	string	body
`kind`requiredWhich kind of yes: a grant…	"capability" \| "folder" \| "shelf" \| "release" … (7)	body
`what`requiredThe capability id, folder, shelf, released…	string	body

What comes back

Field	Type
`ok`Always true	true

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":"capability","what":"2026-08-21T09:14:02.000Z"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

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