---
title: "Answer something that waits on you"
method: POST
path: "/v1/needs-you/{id}/answer"
tags: ["Board"]
---

# Answer something that waits on you

`POST /v1/needs-you/{id}/answer`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/needs-you/{id}/answer`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Request body

- object: permission: `decision` allow_once | allow_always | deny (with `scope` for allow_always: the rule covers the project or every project), a question permission takes `answers`. question: `text`. credential: `decision` deny (provide the value through the credential request). land: `decision` land | keep | discard. prune: `keep`, the Later tasks to keep (the rest are cleared). device: `decision` device with `device_id` (one of its `choices`), or cancel.
  - `credential` object
    - `value` string, required: Write-only UTF-8 secret, using the existing secret store.
    - `scope` 'agents' | 'project' | 'conversation', required
  - `decision` 'allow_once' | 'allow_always' | 'deny' | 'land' | 'keep' | 'discard' | 'cancel' | 'device'
  - `device_id` string: device, with decision `device`: the computer that runs it (a `device_id` of its `choices`).
  - `scope` 'project' | 'everywhere'
  - `text` string
  - `answers` object
  - `keep` string[]
  - `organization_id` string, uuid: UUIDv7, lowercase canonical form.

## Response `200`

Default Response

- object
  - `answered` true, required
  - `item` NeedsYouItem, required
    - `id` string, required: Stable while the item waits: perm_<permission id>, ask_<report id>, cq_<conversation id>, cred_<request id>, land_<task id>, prune_<hash>, oq_<id> (your orchestrator’s question), dev_<request id> (a request for your computer: it waits for your computer, or for you to pick which one runs it).
    - `kind` 'permission' | 'question' | 'credential' | 'land' | 'prune' | 'device', required
    - `ask` string, required: What is asked, one line.
    - `task_id` string, nullable, required
    - `conversation_id` string, nullable, required
    - `project_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
    - `harness` 'claude' | 'codex', nullable, required
    - `since` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `options` string[]: question: suggested answers (free text always works).
    - `option_details` object: Optional explanation keyed by the exact suggested answer label: what this choice does, what the person supplies and what happens next. The first option is the recommendation. No secret values.
    - `permission` object
      - `permission_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `tool` string, nullable, required
      - `detail` string, required
      - `decisions` string[], required
      - `rule` object, required: What “always allow” adds, spelled out.
        - `tool` string, required
        - `pattern` string, required
      - `questions` unknown[]: The agent’s question (AskUserQuestion), as the permission request carries it.
        - unknown
    - `credential` object
      - `request_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `site` string, required
      - `fields` string[], required
      - `kind` 'environment'
      - `name` string
      - `purpose` string
      - `suggested_scope` 'agents' | 'project' | 'conversation'
    - `land` object: land: the finished task’s result, one per task. Land merges it into the project’s default branch (and a linked folder): the Shard app or `shard task land`.
      - `branch` string, required: The task’s result branch: shard/<task id>, its workers’ branches merged by its master.
      - `base_branch` string, nullable, required
      - `changes` object, required
        - `files` integer, required
        - `insertions` integer, required
        - `deletions` integer, required
        - `commits` integer, required
        - `uncommitted` boolean, required
    - `prune` object
      - `task_ids` string[], required
    - `device` object: device: a request for your computer. Without `choices`: your orchestrator asked your computer for something while it was offline; it runs when your computer is back (the Shard app open). With `choices`: you pick the computer that runs it. `cancel` drops it.
      - `request_id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `kind` string, required
      - `what` string, required: What it asks of your computer, one line: “list ~/code”.
      - `choices` object[]: Set when you pick the computer that runs it (“Which computer should run this: list ~/code?”): your computers online for its project. Answer decision `device` with one’s `device_id`.
        - `device_id` string, required
        - `name` string, required
        - `os` string, nullable, required
    - `input_id` string: Your orchestrator input it comes from (oq_, dev_).
  - `rule_id` string, nullable, required

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)