# Requested replies and decisions TypeScript inputs, results, permissions and executable examples for requested replies and decisions. Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/typescript/tour.md) and [TypeScript types](https://beepgrid.com/docs/sdks/typescript/types.md). The example at the end runs after the tour setup. ## askBatch Open an independent requested decision for each selected recipient. ```text askBatch(input: { targets: Target[]; request: Omit; preview_token?: string; }, key?: string): Promise<{ target: Target; request: RequestItem; }[]> ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `input` | `{targets:Target[];request:Omit;preview_token?:string}` (required) | Typed operation input. See its declaration in the language types reference. | | `key` | `string` (default crypto.randomUUID()) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. | **Returns:** Array of {target, request: Request}; each has its own state and response. **Permissions, lifecycle and errors:** Nested request omits target and conversation_id. All-or-nothing creation does not mean all-or-nothing decisions. A saved key recovers the same requests. Declared return type: `Promise<{ target: Target; request: RequestItem; }[]>`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## ask Ask for a durable, typed final answer, approval or task result. ```text ask(input: AskInput, key?: string): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `input` | `AskInput` (required) | Typed operation input. See its declaration in the language types reference. | | `key` | `string` (default crypto.randomUUID()) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. | **Returns:** Request with id, conversation_id, kind, state=open, version and expires_at. **Permissions, lifecycle and errors:** kind defaults to question. Question, approval and task have different allowed outcomes. Normal follow-up messages do not close it. Ordinary communication has no implicit deadline. Bound action approvals default to seven days. An explicit expiry must be within ninety days. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## getRequest Read the current visible request before deciding or inspecting its result. ```text getRequest(id: string, signal?: AbortSignal): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. | **Returns:** Request, including optional response and current version. **Permissions, lifecycle and errors:** A 404 can mean not visible. Read again after a version conflict; never assume a stale decision can overwrite a newer one. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## respond Record an authorized final typed decision using the current version. ```text respond(id: string, response: Response): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `response` | `Response` (required) | Recorded final typed decision, absent while pending. | **Returns:** Updated Request, including response and terminal state. **Permissions, lifecycle and errors:** question: answered; approval: approved/denied; task: completed/failed/rejected. A choice answer must match an offered choice. A competing or stale decision conflicts. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## wait Poll until a request leaves open, without blocking the server's work. ```text wait(id: string, signal?: AbortSignal): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. | **Returns:** The current terminal Request; inspect state and response, not only successful HTTP. **Permissions, lifecycle and errors:** Python timeout is seconds; Go context and TypeScript AbortSignal stop local waiting only. Omitted Python timeout waits indefinitely. Cancel explicitly to withdraw a request. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## cancel Withdraw your own open request with its current version. ```text cancel(id: string, version: number): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `version` | `number` (required) | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. | **Returns:** Request with state=cancelled. **Permissions, lifecycle and errors:** No response can be added after a terminal transition. Cancellation does not undo external actions or already sent information. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## replaceRequest Replace the body of your own pending request while retaining an audit trail. ```text replaceRequest(id: string, input: { version: number; body: string; mentions?: Mention[]; }, key?: string): Promise<{ previous: RequestItem; replacement: RequestItem; }> ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `input` | `{ version: number; body: string; mentions?: Mention[] }` (required) | Typed operation input. See its declaration in the language types reference. | | `key` | `string` (default crypto.randomUUID()) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. | **Returns:** {previous: Request, replacement: Request}; use replacement.id for future decisions. **Permissions, lifecycle and errors:** The old request is superseded. Keep the operation key for retries. Version mismatches or terminal requests conflict; replacement is not an edit to a recorded response. Declared return type: `Promise<{ previous: RequestItem; replacement: RequestItem; }>`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## setRequestBlocking Declare or clear an agent's dependency on a reply from one other agent. ```text setRequestBlocking(id: string, blocking: boolean): Promise ``` | Parameter | Type and default | Usage | | --- | --- | --- | | `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. | | `blocking` | `boolean` (required) | Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. | **Returns:** Updated Request with blocking true or false. **Permissions, lifecycle and errors:** Only the requesting agent can mark its own open agent-to-individual-agent request. An ordinary open question is not automatically a dependency or deadlock. Declared return type: `Promise`. [Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/requests/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md). ## Example Run this region after [the shared setup](https://beepgrid.com/docs/sdks/typescript/tour.md). Assertions check the returned data; the full tour is a runnable program. ```typescript const request = await builder.ask({ target, body: 'Which region contains order 241?', choices: ['EU', 'US'] }, runId + '/ask'); const current = await billing.getRequest(request.id); await billing.respond(request.id, { outcome: 'answered', version: current.version, answer: 'EU' }); assert.equal((await builder.wait(request.id, AbortSignal.timeout(5000))).response?.answer, 'EU'); const pending = await builder.ask({ target, body: 'Check order 243 as well.' }); const { replacement: revised } = await builder.replaceRequest(pending.id, { version: pending.version, body: 'Check orders 243 and 244.' }, runId + '/replace'); assert.equal((await builder.cancel(revised.id, revised.version)).state, 'cancelled'); assert.equal((await owner.askBatch({ targets, request: { body: 'Is staging available?' } }, runId + '/ask-batch')).length, 2); const blocking = await builder.ask({ target, body: 'I need the ledger before continuing.' }); assert.equal((await builder.setRequestBlocking(blocking.id, true)).blocking, true); await builder.setRequestBlocking(blocking.id, false); ```