Querying basics

Most list queries in the External API are exposed as Relay-style connections with cursor-based pagination, projection, filtering, and sorting. Once you understand the shape on one query, the others all follow the same pattern.

All examples on this page require a JWT — get one from the homepage first.

Projection: ask only for what you need

GraphQL only returns the fields you request, and the server only loads the database columns and navigations needed to fulfil the request. Asking for more fields makes the response bigger and the underlying SQL more expensive — keep selections tight.

query currentOrganization {
organization {
  id
  name
}
}

organization returns your authenticated board's record. The organization ID is taken from your JWT — there's no argument.

Connection shape: nodes, pageInfo, totalCount

List queries don't return a flat array — they return a connection object. The most useful fields:

• nodes — a flattened list of the returned entities. Use this when you don't need cursors.
• edges — [{ node, cursor }]. Use this when you want the cursor for each row.
• pageInfo — { hasNextPage, hasPreviousPage, startCursor, endCursor }.
• totalCount — the total number of rows matching the query (regardless of paging).

query firstMembers($first: Int) {
members(first: $first) {
  totalCount
  nodes {
    id
    identification
    status
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

Pagination: cursor-based, not offset

Use first: N to fetch the first N rows, then after: "<endCursor>" to fetch the next page using the endCursor returned from the previous response. There is no skip / take / page argument — cursors are the only paging mechanism.

query nextMembersPage($first: Int, $after: String) {
members(first: $first, after: $after) {
  nodes {
    id
    identification
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

To paginate backwards through a list, use last: N together with before: "<startCursor>". Mixing forward and backward args (first with before, etc.) is invalid.

Filtering

Connection queries accept a where argument with the operators GraphQL clients expect: eq, neq, contains, startsWith, gt, lt, in, and, or. Only fields the schema explicitly allows can be filtered — an unbound field returns a schema error at parse time. The per-query guides in this section list the bound fields for each query.

query searchMembers($where: MemberFilterInput) {
members(where: $where, first: 20) {
  totalCount
  nodes {
    id
    identification
    status
  }
}
}

String contains is case-insensitive (custom handler).

Sorting

Connection queries accept order — an array of { field: ASC | DESC } objects. As with where, only declared fields can be sorted.

query orderedMembers($order: [MemberSortInput!]) {
members(order: $order, first: 5) {
  nodes {
    id
    identification
    memberSince
  }
}
}

Combine them

where, order, first/after are all independent — combine them freely.

query findRecentActiveEvents($where: EventFilterInput, $order: [EventSortInput!], $first: Int) {
events(where: $where, order: $order, first: $first) {
  totalCount
  nodes {
    id
    name
    registrationEnd
    isActive
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

Organization scoping is automatic

Every query that returns organization-owned data filters to your board automatically — derived from the organizationId claim on your JWT. You can't (and don't need to) pass an organizationId argument. A query for "all events" returns your board's events, never another board's data.

Schema-level reference

The other pages in this section list each query's sortable and filterable fields. For everything else — every field on every type — open /graphql to browse the live schema in Nitro.