---
title: "List what waits on you"
method: GET
path: "/v1/needs-you"
tags: ["Board"]
---

# List what waits on you

`GET /v1/needs-you`

## Request

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

Everything waiting on a person, oldest first: permission requests, agents’ questions, credential requests, unlanded work of finished tasks and the bundled prompt for old Later tasks. Answer any of them with POST /v1/needs-you/{id}/answer.

## Query parameters

- `organization_id` string, uuid
- `project_id` string, uuid: UUIDv7, lowercase canonical form.

## Response `200`

Default Response

- object
  - `data` 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_).

## 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)