Run a view as a board

GET

/v1/views/{viewId}/board

const url = 'https://api.pealboard.com/v1/views/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/board';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.pealboard.com/v1/views/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/board \
  --header 'Authorization: Bearer <token>'

The view’s issues arranged into columns by its groupBy: a project field, a label prefix, assignees, milestones, or state.

A project field of any kind makes columns, and where they come from depends on the kind: a single select’s options in the order the project shows them; an iteration field’s own iterations, current before completed; one column per month for a date; one column per distinct value for a number or a text field, drawn from the issues this board covers and capped at forty. Every board has a final column for issues with no value, because the work nobody has triaged is the work a board exists to surface.

When the grouping names a project field by name, the project is resolved in this order: groupBy.projectId if the view names one; otherwise the view’s own project filter; otherwise the project carrying the most of this board’s issues, with the lowest-numbered project breaking a tie. board.project says which was chosen, so a screen can name it — two projects in one workspace can both have a Status.

Each column carries its own count and its own nextCursor. To page one column, send column naming it together with cursor; the other columns then come back empty, because a client paging one column is not redrawing the board.

A view whose layout is not board can still be run as one, provided it has a groupBy.

Access. Requires the viewer role or above (viewer, member, admin, owner). A board is a way of arranging issues the member may already read. API-key scope: issues:read.

Authorizations

bearerAuth

Parameters

Path Parameters

viewId

required

From GET /v1/views.

string format: uuid

From GET /v1/views.

Query Parameters

column

Page only this column. Its id comes from a previous board.

string

Page only this column. Its id comes from a previous board.

cursor

That column’s nextCursor from the previous page.

string

That column’s nextCursor from the previous page.

limit

Cards per column. Defaults to 20.

integer

>= 1 <= 100

Cards per column. Defaults to 20.

Responses

200

The board.

application/json

object

viewId

required

A UUID this API issued.

string format: uuid

groupBy

required

One of:

object

kind

required

string

Allowed values: project_field

fieldNodeId

Any kind of project field. A single select’s columns are its options, an iteration field’s are its iterations, a date’s are months, and a number’s or a text field’s are the distinct values this board holds.

string

fieldName

For a view saved before any project existed. Resolved when the board is run.

string

projectId

A UUID this API issued.

string format: uuid

field

required

object

required

A UUID this API issued.

string format: uuid

nodeId

required

What every field value is keyed by. Survives a rename.

string

name

required

string

dataType

required

GitHub’s ProjectV2FieldType: TEXT, SINGLE_SELECT, NUMBER, DATE, ITERATION, and the rest.

string

options

required

In the order the project shows them. Null unless the field is a single select.

Array<object> | null

object

required

string

name

required

string

color

required

string

description

required

string

isIssueField

required

True when the field is an organization issue field linked into this project.

boolean

project

required

The project the columns came from, when they came from one. Present so the board can say which: a workspace can have two projects that both have a Status, and columns with nothing naming their project are columns nobody can tell are the wrong ones. Null for a board grouped by state, assignee, milestone or a label prefix.

object

required

A UUID this API issued.

string format: uuid

nodeId

required

string

number

required

number

title

required

string

url

required

The project on GitHub.

string format: uri

columns

required

Array<object>

object

required

Stable within the board: an option id, a label name, a login, a milestone id, or a state.

string

name

required

What the column is headed.

string

color

required

string | null

count

required

How many issues are in the column, which is more than the page returned.

number

cards

required

Array<object>

object

required

A UUID this API issued.

string format: uuid

nodeId

required

string

number

required

number

title

required

string

body

required

What the person typed. The attribution block Pealboard writes for a portal request or for a member, and the hidden marker beside it, are stripped here and kept on GitHub. Sending an edited body back keeps them.

string | null

state

required

GitHub’s own word for whether the issue is open or closed.

string

Allowed values: open closed

stateReason

required

Why the issue is in this state. Null while it is open. duplicate is what makes a portal show a request as Merged.

string | null

Allowed values: completed not_planned duplicate reopened

duplicateOfIssueId

required

The issue this one was closed as a duplicate of, when the close went through Pealboard with duplicateOfIssueId. GitHub takes the canonical issue and never sends it back, so a duplicate closed on GitHub itself is stateReason: duplicate with null here. Cleared on reopen.

string | null format: uuid

repository

required

object

required

A UUID this API issued.

string format: uuid

nodeId

required

string

fullName

required

string

ownerLogin

required

string

name

required

string

private

required

boolean

author

required

object

required

GitHub’s numeric user id.

number

login

required

string

avatarUrl

required

string | null format: uri

type

required

User, Bot or Organization.

string

authoredBy

required

object

membershipId

required

A UUID this API issued.

string | null format: uuid

name

required

The display name. Never an email address.

string

kind

required

team: a workspace member, the same word a portal uses for the same people. customer: a portal customer, whose request or comment the App wrote on their behalf; membershipId is null.

string

Allowed values: team customer

assignees

required

Array<object | null>

object

required

GitHub’s numeric user id.

number

login

required

string

avatarUrl

required

string | null format: uri

type

required

User, Bot or Organization.

string

labels

required

Array<object>

object

nodeId

required

string

name

required

string

color

required

string

milestone

required

object

required

A UUID this API issued.

string format: uuid

nodeId

required

string

repositoryId

required

A UUID this API issued.

string format: uuid

number

required

number

title

required

string

description

required

string | null

state

required

string

Allowed values: open closed

dueOn

required

string | null format: date-time

issueType

required

The organization issue type, when the organization uses them.

object

required

number

nodeId

required

string

name

required

string

color

required

string | null

subIssues

required

object

total

required

number

completed

required

number

percentCompleted

required

number

parent

required

The issue this one was split out of, when it is a sub-issue. The children are GET /v1/issues/{issueId}/sub-issues.

object

required

Null when the parent’s repository is not synced, so Pealboard holds no row for it.

string | null format: uuid

number

required

integer

repository

required

object

required

A UUID this API issued.

string | null format: uuid

fullName

required

string

title

required

string | null

projectItems

required

Array<object>

object

itemNodeId

required

Pass this to the project item routes.

string

projectId

required

A UUID this API issued.

string format: uuid

projectNodeId

required

string

projectTitle

required

string

fieldValues

required

Keyed by the field’s node id, which is what GitHub identifies it by.

object

key

additional properties

One of:

object

type

required

string

Allowed values: text

text

required

string

requests

required

Empty for an issue no portal knows about, which is most of them.

Array<object>

A portal request that points at this issue. One issue maps to at most one request per portal.

object

required

A UUID this API issued.

string format: uuid

portalId

required

A UUID this API issued.

string format: uuid

portalSlug

required

Lowercase letters, digits and hyphens.

string

>= 2 characters <= 40 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/

portalName

required

string

number

required

The portal-local request number.

string

visibility

required

string

Allowed values: private company public

voteCount

required

number

commentsCount

required

number

locked

required

boolean

htmlUrl

required

The issue on GitHub.

string format: uri

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

closedAt

required

string | null format: date-time

syncedAt

required

When Pealboard last read this issue from GitHub.

string format: date-time

nextCursor

required

Pass back as cursor with column naming this column to page it.

string | null

Example

{
  "groupBy": {
    "kind": "project_field"
  },
  "columns": [
    {
      "cards": [
        {
          "id": "8f1c2b3e-0a4d-4e6f-9c11-2d3e4f5a6b7c",
          "nodeId": "I_kwDOAbc123",
          "number": 412,
          "title": "Board columns lose their order after a drag",
          "body": "Dragging a card to the last column reorders every other column.",
          "state": "open",
          "stateReason": null,
          "duplicateOfIssueId": null,
          "repository": {
            "id": "1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9",
            "nodeId": "R_kgDOAbc123",
            "fullName": "mersoft-corp/pealboard-api",
            "ownerLogin": "mersoft-corp",
            "name": "pealboard-api",
            "private": false
          },
          "author": {
            "id": 4891,
            "login": "jdoe",
            "avatarUrl": null,
            "type": "User"
          },
          "authoredBy": null,
          "assignees": [
            {
              "id": 5120,
              "login": "asmith",
              "avatarUrl": null,
              "type": "User"
            }
          ],
          "labels": [
            {
              "nodeId": "LA_kwDOAbc",
              "name": "bug",
              "color": "d73a4a"
            }
          ],
          "milestone": null,
          "issueType": null,
          "subIssues": null,
          "parent": null,
          "projectItems": [],
          "requests": [],
          "commentsCount": 3,
          "locked": false,
          "htmlUrl": "https://github.com/mersoft-corp/pealboard-api/issues/412",
          "createdAt": "2026-09-01T09:14:00.000Z",
          "updatedAt": "2026-09-08T16:02:11.000Z",
          "closedAt": null,
          "syncedAt": "2026-09-08T16:02:14.000Z"
        }
      ]
    }
  ]
}

401

No valid credentials.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

403

Authenticated, but not permitted.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

404

No such resource, or it is not visible to you.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

409

The request conflicts with the current state.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

422

The request did not match the expected shape.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

429

Rate limited. Retry after the interval in the header.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

502

GitHub or another dependency refused or did not answer. Nothing in the workspace changed.

application/json

object

error

required

object

code

required

A stable identifier for the kind of failure. Safe to branch on.

string

message

required

What went wrong, written for a person.

string

detail

Structured particulars, when there are any.

object

key

additional properties

remedy

What to do about it, when there is something to do.

string

requestId

required

Quote this when asking about a specific failure.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

Run a view as a board

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Example

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

422

Examplegenerated

429

Examplegenerated

502

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated