---
title: "Get the board"
method: GET
path: "/v1/board"
tags: ["Board"]
---

# Get the board

`GET /v1/board`

## Request

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

Every task of the projects you can access (a user: every project of the organization; an API key: its project), the reports sealed for them, everything waiting on you, the approval policy and your seen marks. Reading it never wakes a computer. Follow changes with GET /v1/board/feed from `cursor`.

## Query parameters

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

## Response `200`

Default Response

- Board
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `conversations` Conversation[]
    - `id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `key` string, required
    - `name` string, required
    - `title` string, required
    - `summary` string, required
    - `harness` 'claude' | 'codex', required
    - `harness_session_id` string, nullable, required
    - `route` 'terminal' | 'acp' | 'codex-app' | 'codex-cloud' | 'claude-desktop' | 't3-ssh', required
    - `role` 'main' | 'fork' | 'spawn' | 'join', required
    - `join_mode` 'reviewer' | 'worker', nullable, required
    - `orchestrator_conversation_id` string, nullable
    - `orchestrator_input_id` string, nullable
    - `settled_reason` 'computer_suspended' | 'computer_failed', nullable: The computer suspended or failed while a native turn was active. Cleared by later live activity. Null or absent does not establish that a turn finished.
    - `parent_id` string, nullable, required
    - `root_id` string, required
    - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `worktree_path` string, required
    - `branch` string, required
    - `base_commit` string, required: The commit the conversation started from; empty for a home conversation.
    - `base_branch` string, nullable, required
    - `repo_remote` string, required
    - `home` boolean, required: A conversation on your machine’s home: no repository (`repo_remote`, `branch` and `base_commit` are empty). Its agent runs in `/home/user` on a computer from your machine environment and starts threads in the project’s repositories.
    - `state` 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived' | 'deleted', required: `deleted` only on the one feed delivery of a deleted conversation.
    - `changes` object, required
      - `files` integer, required
      - `insertions` integer, required
      - `deletions` integer, required
      - `commits` integer, required
      - `uncommitted` boolean, required
    - `landed` object, nullable, required
      - `how` 'merged' | 'pushed' | 'pr' | 'kept' | 'discarded' | 'no_changes', required
      - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `ref` string, required
    - `pending_move` object, nullable, required
      - `to` string, required
      - `requested_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `initial_input` object: Only a qualified computer guest receives its exact bound initial-input receipt metadata.
      - `protocol` 1, required
      - `input_id` string, required
      - `received` boolean, required
      - `recovery_blocked` boolean, required
      - `halted` boolean, required
      - `sha256` string, required
      - `bytes` integer, required
    - `brief` string, nullable, required
    - `last_activity_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `ended_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `model` string, nullable, required
    - `effort` string, nullable, required
    - `title_prefix` string, nullable: The marker the conversation’s Claude session title starts with; an empty string for none. Null: the default “☁ ”.
    - `started_by` object, nullable: The user who started the conversation: the signed-in user, or the user who created the API key that started it. A conversation a guest spawns, forks or joins carries its VM creator’s user. Null for conversations started before this was recorded and for a key without a known creator.
      - `user_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `question` string, nullable: Why the conversation needs you: the agent’s question or the reason its turn stopped (“Codex reached its usage limit; try again at 4:40 AM.”), on one line of up to 500 characters. Set while `state` is `needs_you`; null otherwise, and for a permission prompt that asks no question.
    - `title_short` string, nullable, required: The agent’s own short name for the conversation (“CSV export for todo list”): Claude Code’s generated title or the Codex thread name, on one line. Null until the agent has named it; show `title` meanwhile.
    - `updated_at` string, date-time, required: When something this conversation shows last changed (state, titles, summary, changes, landing, question, activity). GET /v1/conversations?updated_after= filters on it.
    - `deleted_at` string, date-time, nullable: Set once the conversation was deleted: a feed delivers it this one time, with its content cleared; remove it. Lists leave it out and it reads 404.
    - `parent_deleted` boolean: Its parent conversation was deleted (`parent_id` reads 404).
    - `needs_you_reason` 'permission' | 'question' | 'sign_in' | 'turn_failed', nullable: Why the conversation needs you, while `state` is `needs_you`: `permission` (the agent asks to use a tool), `question` (the agent asks you something), `sign_in` (the agent’s account must sign in again) or `turn_failed` (its turn stopped, for example on a usage limit; `question` says why). Null otherwise.
    - `seen_at` string, date-time, nullable: When you last opened this conversation, on any of your devices (POST /v1/conversations/marks `seen`). A conversation you never opened reads the time your marks start from (no earlier than when you joined its organization). A result is new to you when the conversation finished after this time. Each person has their own. Present on GET /v1/conversations, GET /v1/conversations/{id}, GET /v1/conversations/feed and POST /v1/conversations/marks; absent on other answers, which do not read marks.
    - `dismissed_at` string, date-time, nullable: When you archived this conversation from your inbox, on any of your devices (POST /v1/conversations/marks `dismissed`); null when you have not, or restored it. Each person has their own. Present where `seen_at` is.
  - `tasks` Task[], required
    - `id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `home` boolean, required: A personal task: it runs on the project’s machine home, without a repository.
    - `text` string, required: The person’s exact words. Never rewritten.
    - `title` string, nullable, required: A short title; null until it arrives (show `text` meanwhile).
    - `waiting` object, nullable, required: Set while the task waits to start or continue (no linked agent is running); null otherwise. `until`: when the wait ends by itself (a usage reset), to show in local time.
      - `reason` string, required: Why the task waits for its agent: usage_limit, capacity_wait, agent_not_running, …
      - `message` string, required: One line for the row, in plain words: “Getting its computer ready”, “Waiting for a free computer”, “Claude usage resets 15:00 UTC”.
      - `since` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `until` string, date-time, nullable: RFC 3339 UTC timestamp with Z.
    - `activity` string, nullable, required: Working: what it is doing now, one line, from its working conversation (a worker before the master); null otherwise. Changes arrive through the feed.
    - `bucket` 'now' | 'next' | 'later', required
    - `position` number, required: Order within the bucket: lower comes first.
    - `state` 'queued' | 'working' | 'needs_you' | 'done' | 'unverified' | 'failed', required
    - `parent_task_id` string, nullable, required
    - `suggested` boolean, required: Proposed by an agent; it sits in Later until the person keeps it.
    - `harness` 'claude' | 'codex', nullable, required
    - `master_id` string, nullable, required
    - `conversations` object[], required: The conversations that work on it: the master first, then its workers.
      - `id` string, required
      - `role` 'master' | 'builder' | 'reviewer' | 'light' | 'hard' | 'worker', required
      - `step_id` string, nullable, required
    - `plan` object, nullable, required
      - `summary` string, required
      - `steps` object[], required
        - `id` string, required
        - `text` string, required
        - `state` 'queued' | 'working' | 'done' | 'failed', required
        - `conversation_id` string, nullable, required
        - `outcome` string, nullable, required: Done: the one-line outcome of the report that finished it.
        - `evidence` string[], required: Done: that report’s evidence labels.
        - `report_id` string, nullable, required
        - `now` string, nullable, required: Working: what its conversation is doing now, one line (its live title); null otherwise.
    - `landed` object, nullable, required: Where the task’s current result landed (the commit and the branch it is in); null until it did. Done and landed is shipped.
      - `sha` string, required: The result commit, contained in `into`.
      - `into` string, required: The branch it landed in: the project’s default branch on the project hub.
      - `branch` string, required: The task’s result branch (shard/<task id>), where its master merged its workers’ branches.
      - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `latest_report_id` string, nullable, required
    - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `seen_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `cleared_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `deleted_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `reports` TaskReport[], required: Reports of the board’s tasks, oldest first.
    - `id` string, required
    - `task_id` string, required
    - `project_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `milestone` 'planned' | 'needs_you' | 'answered' | 'part_landed' | 'done' | 'failed', required
    - `title` string, required: One line: “Limits page updated”.
    - `outcome` string, required: One line: what changed for the person.
    - `plan` object, nullable, required
      - `summary` string, required: The master’s reading of the task, one or two lines.
      - `steps` object[], required
        - `id` string, required
        - `text` string, required
    - `steps_done` string[], required: The plan steps this report finishes.
    - `options` string[], nullable, required: needs_you: 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.
    - `evidence` TaskEvidence[], required: Proof. A done report without evidence leaves its task unverified.
      - `kind` 'command' | 'probe' | 'screenshot' | 'url' | 'file', required
      - `label` string, required: The chip: “tests 48/48”, “live probe 200”, “screenshot”.
      - `detail` string, nullable, required: The command, URL or path behind it.
      - `output` string, nullable, required: Captured output (a command’s tail, a probe’s response head), as the agent sent it.
      - `path` string, nullable, required: A file on the project drive (screenshot, log), readable after the worker’s computer is gone.
      - `file` object, nullable
        - `path` string, required
        - `sha256` string, required
        - `size` integer, required
        - `content_type` string, nullable, required
      - `width` integer: A screenshot’s width in pixels.
      - `height` integer: A screenshot’s height in pixels.
      - `thumbnail` MediaThumbnail
        - `path` string, required
        - `sha256` string, required
        - `size` integer, required
        - `content_type` string, required
        - `width` integer, required
        - `height` integer, required
    - `media` TaskMedia[], required
      - `kind` 'image' | 'video' | 'pdf' | 'file', required
      - `name` string, required
      - `path` string, required: Where it lives on the project drive.
      - `width` integer: An image’s width in pixels.
      - `height` integer: An image’s height in pixels.
      - `file` object
        - `path` string, required
        - `sha256` string, required
        - `size` integer, required
        - `content_type` string, nullable, required
      - `thumbnail` MediaThumbnail
        - `path` string, required
        - `sha256` string, required
        - `size` integer, required
        - `content_type` string, required
        - `width` integer, required
        - `height` integer, required
    - `landed` object, nullable, required
      - `how` 'merged' | 'pushed' | 'pr' | 'kept' | 'discarded' | 'no_changes', required
      - `at` string, date-time, required: RFC 3339 UTC timestamp with Z.
      - `ref` string, required
    - `author_id` string, required
    - `harness` 'claude' | 'codex', required
    - `sealed_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
    - `seen_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `needs_you` NeedsYouItem[], required: Oldest blocking first.
    - `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_).
  - `policy` ApprovalPolicy, required: ask: every permission request comes to Needs you. routine: tests, builds, reads and installs are approved without you. trusted: everything except deploys, pushes to main and spending.
    - `default` 'ask' | 'routine' | 'trusted', required
    - `projects` object, required: Per-project overrides of the default, by project id.
    - `rules` ApprovalRule[], required
      - `id` string, required
      - `tool` string, required: The tool as the harness names it (Bash, WebFetch, Edit).
      - `pattern` string, required: The command prefix (or path, URL) it allows; empty allows every use of the tool.
      - `project_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
      - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `reports_seen_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `cursor` string, required: Follow the board from this answer on: GET /v1/board/feed?cursor=.

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