List boards

Page through the boards you can see, with search, sorting, and filters by view, access level, owner, or date.

On this page

Views
Request
Response
Top level
Board object
Freshness
Paging
Errors

A board holds an ordered set of nodes. This returns the boards the credential can see on the account it acts as, a page at a time, newest first unless you ask for another order. It searches and sorts on the server, so a team with tens of thousands of boards pages as quickly as one with ten.

GEThttps://api2.rundiffusion.com/api/v2/boards

AcceptsOAuth device flowPersonal API Access TokenCompany API Access Token

Which boards those are depends on the account. On a personal account it is your own boards, and nothing else. On a team it follows the same rules the app does:

Access level	Who sees it
`SHARED`	everyone on the team
`RESTRICTED`	the members listed on it, the owner always among them
`PRIVATE`	the owner alone

A member holding Can manage everyone's generations and boards (MANAGE_ALL_GENERATIONS) can see every board on the team regardless of level. See Identity for reading your own permissions.

This listing reads one account at a time: omit team_id for your own boards, or name a single team.

Views

view picks which of those boards to list, the same four ways the app's Boards page offers:

`view`	The boards listed
`all`	your own boards, every `SHARED` board, and the `RESTRICTED` boards you are a member of
`mine`	the boards you own, at any access level
`shared_with_me`	every `SHARED` board and the `RESTRICTED` boards you are a member of, your own included
`everyone`	every board on the team. Needs `MANAGE_ALL_GENERATIONS` on the team, or the request returns `403`

Leave it out and you get everyone if you hold MANAGE_ALL_GENERATIONS and all otherwise, which is everything you can see either way. On a personal account every board is yours: shared_with_me returns none, and every other view, everyone included, returns them all without needing a permission.

Request

Headers

AuthorizationstringRequired: Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See Authentication.Authorization: Bearer eyJhbGciOi…

Query parameters

team_idstringoptional: The team whose boards to read, one per request. Omit it to read your personal account. Part of the account selection rather than a filter, so it behaves identically on every endpoint.https://api2.rundiffusion.com/api/v2/boards?team_id=Tq8vNc…
limitintegeroptionaldefault 24: Boards per page, 1 to 100.limit=100
cursorstringoptional: The next_cursor from a previous response. Keep every other parameter identical between pages: the cursor is a position within one listing, so changing the view, the sort, the order, the search, or a filter mid-walk returns 400 INVALID_CURSOR rather than a silently different page. limit may change.
viewstringoptional: Which of the team's boards to list. See Views. Defaults to everyone for a holder of MANAGE_ALL_GENERATIONS and to all otherwise.view=shared_with_me
qstringoptional: Case-insensitive substring match on the title, the description, or the value of any board custom field the company defines, up to 200 characters. Percent and underscore match themselves rather than acting as wildcards.q=hero
sortstringoptionaldefault created: Result order. custom_field orders by the field named in custom_field_key. Boards with no creation time, no description, or no value for the field sort last in either direction. Ties always break on the board ID, so a walk never repeats or skips a board.sort=title
orderstringoptional: Which direction sort runs in. Defaults to desc (newest first) for created and to asc for every other sort.sort=created&order=asc
custom_field_keystringoptional: The key of the board custom field to sort by. Required with sort=custom_field. Each board's custom_fields lists the keys.sort=custom_field&custom_field_key=project_number
access_levelstringoptional: Return only boards at this access level. A personal board counts as PRIVATE.access_level=SHARED
owner_user_idstringoptionalAccepts multiple: Return only boards owned by one user, or by any of several, comma-separated, up to 100. Useful on a team; on a personal account every board is already yours.owner_user_id=k3PqV9…,Hn2Lw8…
start_utcstring (ISO 8601)optional: Start of the window, inclusive, in UTC. A board created at exactly this instant is included.https://api2.rundiffusion.com/api/v2/boards?start_utc=2026-07-01T00:00:00Z
end_utcstring (ISO 8601)optional: End of the window, exclusive, in UTC. A board created at exactly this instant is NOT included.https://api2.rundiffusion.com/api/v2/boards?end_utc=2026-08-01T00:00:00Z

curl -G https://api2.rundiffusion.com/api/v2/boards \
  -H "Authorization: Bearer $RUNDIFFUSION_TOKEN" \
  --data-urlencode "team_id=Kp7mZq…" \
  --data-urlencode "q=hero" \
  --data-urlencode "sort=title"

const params = new URLSearchParams({ team_id: 'Kp7mZq…', q: 'hero', sort: 'title' });
const page = await fetch(
  `https://api2.rundiffusion.com/api/v2/boards?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.RUNDIFFUSION_TOKEN}`,
    },
  },
).then(r => r.json());

for (const board of page.data) {
  console.log(board.id, board.title, board.access_level);
}

page = requests.get(
    f"{BASE}/boards",
    headers=HEADERS,
    params={"team_id": team_id, "q": "hero", "sort": "title"},
).json()

for board in page["data"]:
    print(board["id"], board["title"], board["access_level"])

Response

200 OK with one page of boards.

json

{
  "data": [
    {
      "id": "Tq8vNc…",
      "created": "2026-07-30T14:02:11+00:00",
      "title": "Hero shots",
      "description": "Landing page art",
      "access_level": "RESTRICTED",
      "owner_user_id": "k3PqV9…",
      "owner_email": "sam@example.com",
      "team_id": "Kp7mZq…",
      "avatar_url": "https://api2.rundiffusion.com/api/v2/avatars/Av3xQ….png",
      "custom_fields": [
        { "key": "project_number", "label": "Project #", "value": "P-1042" },
        { "key": "client", "label": "Client", "value": null }
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxL…",
  "has_more": true
}

Top level

dataarray: One page of boards, newest first unless you asked otherwise. See Board object below. Empty when nothing matches, which is not an error.
next_cursorstring | null: Pass as cursor for the next page. Null on the last page.
has_moreboolean: Whether another page exists. Prefer this over checking whether data is short.

Board object

idstring: Board ID. Send it as board_id on the board endpoints, and as board_id on Library to filter that board's generations. Example: Tq8vNc….
createdstring (ISO 8601): When it was created, in UTC.
titlestring | null: Board name. Example: Hero shots.
descriptionstring | null: Optional description, null when unset.
access_levelstring: Who can reach the board. Always PRIVATE on a personal account, where there is nobody to share with.
owner_user_idstring: The user who created the board.
owner_emailstring | null: The owner's email address on the team. Null on a personal board, and once the owner has left the team.
team_idstring | null: The team the board belongs to, or null for a personal board.
avatar_urlstring | null: The board's picture, as a png URL you can render directly. Assigned automatically when the board is created, so it is normally set; null only where a board was created without one.
custom_fieldsarray: Every board custom field the company defines, in the company's order, each with key, label and this board's value (null for none). Empty on a personal board.

This listing carries the board itself, not its contents. For the nodes on a board, fetch one board with Get a board.

Status codes

400INVALID_REQUEST: A parameter failed validation, such as a limit outside 1 to 100, a malformed datetime, a sort this endpoint does not offer, or sort=custom_field without custom_field_key. details names the field.
400INVALID_CURSOR: The cursor does not belong to this listing, which happens if you change the view, the sort, the order, the search or a filter partway through a walk. Restart without a cursor.
401TOKEN_INVALID: Missing or invalid credential.
403PERMISSION_DENIED: view=everyone from a caller who does not hold MANAGE_ALL_GENERATIONS on the team.
403ACCOUNT_HEADER_INVALID: The selected account is not one this credential may act on.
429RATE_LIMITED: Too many requests. See Rate limits.

View as Markdown