--- title: "Needs · intentic sandbox API" description: "What an agent asked you to connect or provide before it can go on. Every route in the needs group of the intentic sandbox API." url: "https://intentic.dev/api/needs/" --- 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](#needs-ask) - [This conversation's needs](#needs-mine) - [Withdraw a need](#needs-withdraw) - [What agents are waiting on people for](#needs-list) - [Answer a need](#needs-answer) - [Give a secret a need asked for](#needs-provideSecret) - [The yeses still standing](#needs-grants) - [Take a yes back](#needs-revokeGrant) 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/ask` Ask 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` required The 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` required The 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` required A 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 it answered in this tab curl ```bash 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 ```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/mine` This 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 it answered in this tab curl ```bash curl "$SANDBOX/needs/mine" \ -H "x-intentic-control: $INTENTIC_TOKEN" ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.mine(); ``` **POST`/needs/{id}/withdraw` Withdraw 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` required Which 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 it answered in this tab curl ```bash curl -X POST "$SANDBOX/needs/a1b2c3d4/withdraw" \ -H "x-intentic-control: $INTENTIC_TOKEN" ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.withdraw({ "id": "a1b2c3d4" }); ``` **GET`/needs` What 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 it answered in this tab curl ```bash curl "$SANDBOX/needs" \ -H "x-intentic-control: $INTENTIC_TOKEN" ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.list(); ``` **POST`/needs/{id}/answer` Answer 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` required Which 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` required How 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 it answered in this tab curl ```bash curl -X POST "$SANDBOX/needs/a1b2c3d4/answer" \ -H "x-intentic-control: $INTENTIC_TOKEN" \ -H "content-type: application/json" \ -d '{"answer":{"kind":"decline","note":"…"}}' ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.answer({ "id": "a1b2c3d4", "answer": { "kind": "decline", "note": "…" } }); ``` **POST`/needs/{id}/secret` Give 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` required Which need | string | address | | `value` required The 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 it answered in this tab curl ```bash curl -X POST "$SANDBOX/needs/a1b2c3d4/secret" \ -H "x-intentic-control: $INTENTIC_TOKEN" \ -H "content-type: application/json" \ -d '{"value":"…"}' ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.provideSecret({ "id": "a1b2c3d4", "value": "…" }); ``` **GET`/needs/grants` The 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 it answered in this tab curl ```bash curl "$SANDBOX/needs/grants" \ -H "x-intentic-control: $INTENTIC_TOKEN" ``` TypeScript ```typescript import { sandbox } from "@intentic/sandbox-client"; const result = await sandbox.needs.grants(); ``` **POST`/needs/grants/revoke` Take 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` required Which kind of yes: a grant… | "capability" | "folder" | "shelf" | "release" … (7) | body | | `what` required The capability id, folder, shelf, released… | string | body | ### What comes back | Field | Type | | --- | --- | | `ok` Always true | true | Try it answered in this tab curl ```bash 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 ```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" }); ``` More in Connected systems [Previous ← Capabilities](https://intentic.dev/api/capabilities/)[Next Secrets →](https://intentic.dev/api/secrets/)