getIssueAdmin BFF

/bff/issue/list

Returns a paginated list of issues for the organisation. Supports filtering by project, status category, assignee, reporter, and spam status. The default order is smart — a scrum-backlog composite that surfaces in-progress work first, then waiting, then new, and finally done, breaking ties by priority (higher first) and last activity (fresher first). Clients can override via orderBy=field:direction.

IssuegetBffIssueList

Parameters

15 query

Query parameters

· 15

projectCodestringOptional

Filter by project key (e.g. "PROJ").

ExamplePROJ

statusCategoryIdnumberOptional

Filter by status category id.

Example1

statusCategoryCodestringOptional

Filter by canonical status bucket — new, progress, waiting, done. Preferred over statusCategoryId. Admin-facing sentinels: active (everything except done — the operator default) and all (no status filter, used when searching history).

Exampleactive

statusIdnumberOptional

Filter by a specific status id (a custom org status inside a category).

Example42

assigneeIdnumberOptional

Filter by assignee contact ID.

Example10

unassignedbooleanOptional

When true, restrict to issues with no primary assignee. Takes precedence over assigneeId when both are supplied.

Examplefalse

assigneeFilterstringOptional

Convenience shortcut used by the admin grid: me resolves to the caller's own contact id (server-side lookup, no client round-trip), unassigned maps to unassigned=true, and any other value is interpreted as a shop__contact.external_id (16-char slug) and resolved to that assignee — scoped to the caller organisation so a leaked id from another tenant simply returns no rows. Ignored when assigneeId or unassigned is set explicitly.

Exampleme

reporterIdnumberOptional

Filter by reporter contact ID.

Example5

prioritynumberOptional

Filter by priority (1=low..5=blocker). Rows with a NULL priority column are treated as 2 (the display fallback), matching what the operator sees in the grid.

Range: 1–5

Example3

isSpambooleanOptional

Spam scope: true = only rows classified as spam (is_spam = true), false = only non-spam (is_spam IS NULL OR is_spam = false), omitted = the same as false — the default hides spam so the operator inbox stays focused on actionable tickets. Pass true explicitly (the "Zobrazit spam" chip) to review spam.

Examplefalse

securedOnlybooleanOptional

Advanced filter — true narrows the list to rows where pm__issue.secured_ticket = true. Only meaningful for ORG ROOT viewers (non-root callers already have secured rows hidden by the confidentiality gate, so passing this from a non-root session just yields an empty list). Omitted = no explicit filter (the gate still hides secured rows from non-root viewers).

Examplefalse

contactExternalIdstringOptional

Restrict to issues where a specific contact has any recorded interaction — reporter, assignee, commenter, watcher or mentioned. Value is the 16-char shop__contact.external_id. Used by the "Úkoly" tab on the contact detail; callers filtering by role instead should keep using reporterId / assigneeId.

Example1JfEq22KdM3B456i

orderBystringOptional

Sort key in field:direction format (matches the admin DataGrid wire contract). Supported fields: smart (composite scrum-backlog order — progress > waiting > new > done, then priority DESC, then velocity ASC, then type sort_order ASC, then last-activity DESC — DEFAULT when omitted), insertedDate, updatedDate, priority, velocity, status, subject, issueKey. Unknown fields silently fall back to smart. Direction is ignored for smart (it is a fixed composite).

Examplesmart:asc

pagenumberOptional

Page number (1-based).

Default: 1

Example1

limitnumberOptional

Items per page.

Default: 50

Example50

Response schema

1 status code documented

200Success

itemsobject[]Required

Each array item:

idstringRequired

Issue key (e.g. "PROJ-123"), used as public identifier.

internalIdnumberRequired

Internal numeric ID.

issueKeystringRequired

Issue key.

subjectstringRequired

Issue subject/title.

prioritynumberRequired

Priority number (1=low, 2=normal, 3=high, 4=critical, 5=blocker).

priorityLabelstringRequired

Human-readable priority label.

velocitynumberRequired

Effort/complexity score (0..100). DB default 25. Anchors: 1 trivial, 25 default ~20 min, 50 ~4 h, 75 ~2 days, 90+ split, 100 unsolvable/unclear. Used as the 3rd sort tier in the operator smart backlog (priority → status → velocity).

Range: 0–100

typeobjectRequired

idnumberRequired

Issue type ID (pm__issue_type.id).

codestringRequired

Stable slug (story, epic, task, sub_task, bug, …). Admin resolves the localized label from its dictionary.

iconstring | nullRequired

One of 2:

Variant 1

string

Lucide icon name to render alongside the subject.

Variant 2

null

statusobjectRequired

idnumberRequired

Status ID.

labelstringRequired

Status display label (localized to the viewing organisation).

categoryIdnumberRequired

Status category ID (1=new, 2=progress, 3=waiting, 4=done).

categoryCodestringRequired

Status category code.

assigneeobject | nullRequired

One of 2:

Variant 1

idnumberRequired

Contact ID.

externalIdstring | nullRequired

One of 2:

Variant 1

string

Public contact identifier used in admin URLs (/contact/{externalId}) and in /bff/contact/detail?customerId=.... null for legacy rows that predate the external-id backfill; the UI should render the name without a link in that case.

Variant 2

null

namestringRequired

Full name.

emailstring | nullRequired

One of 2:

Variant 1

string

Contact e-mail. null for phone-only contacts (no e-mail registered) and for contacts anonymised via GDPR. UI should fall back to name or the contact ID.

Variant 2

null

avatarUrlstringOptional

Avatar image URL resolved via core__blob. Falls back through the contact's own avatar_blob_id, then the linked member user's contact avatar_blob_id. Omitted when neither has an avatar uploaded.

Variant 2

null

reporterobject | nullRequired

One of 2:

Variant 1

idnumberRequired

Contact ID.

externalIdstring | nullRequired

One of 2:

Variant 1

string

Variant 2

null

namestringRequired

Full name.

emailstring | nullRequired

One of 2:

Variant 1

string

Contact e-mail. null for phone-only contacts (no e-mail registered) and for contacts anonymised via GDPR. UI should fall back to name or the contact ID.

Variant 2

null

avatarUrlstringOptional

Avatar image URL resolved via core__blob. Falls back through the contact's own avatar_blob_id, then the linked member user's contact avatar_blob_id. Omitted when neither has an avatar uploaded.

Variant 2

null

isSpamboolean | nullRequired

One of 2:

Variant 1

boolean

Spam classification. Null = not yet classified.

Variant 2

null

securedTicketbooleanRequired

pm__issue.secured_ticket. Only ever true in a payload delivered to a ROOT viewer — non-root callers already have the row filtered out. Surface for a "Důvěrné" chip / lock-icon renderer in the grid; never appears alongside a value that non-root operators are allowed to see.

commentsCountnumberRequired

Total comments on the issue across all author kinds. Zero when there are none — the UI should hide the badge for 0 rather than render "0".

hasAttachmentsbooleanRequired

True when the issue has at least one file attached via pm__issue_attachment. Excludes the source-e-mail relation (brj__emailer_received_email.issue_id) — the paperclip icon in the grid must only reflect real file attachments, not the virtual pointer to the inbound mail that lifted the ticket.

isStalebooleanRequired

True when the issue sits in progress or waiting and has not moved in 7+ days (no updated_date bump, no comment). Never true for new or done. Meant as a soft nudge in the grid — not a hard alert.

insertedDateDate | string | string | numberRequired

When the issue was created.

One of 4:

Variant 1

Date

When the issue was created.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

updatedDateDate | string | string | number | nullRequired

One of 2:

Variant 1

Date | string | string | number

Last update timestamp.

One of 4:

Variant 1

Date

Last update timestamp.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

Variant 2

null

ipstring | nullRequired

One of 2:

Variant 1

string

User IP address (IPv4 or IPv6) or null when the origin request has no captured client IP.

When null: the record was created by a server-internal actor (cron, workflow tick, manual admin backfill, mail pipeline) rather than a real HTTP visitor, so no forwarded header was available. UI should treat null as "unknown origin" (typically hide the vikitron.com deep-link and any geolocation badges), not as loopback.

When non-null, the value is the canonicalized form described by API_IP — lowercase IPv6, IPv4-mapped IPv6 unwrapped to plain IPv4, junk collapsed to 127.0.0.1.

Examples1.1.1.12001:4860:4860::8888

Variant 2

null

geoobject | nullRequired

Reporter-IP geolocation (city + country) joined through brj__geo_ip.city_id → brj__geo_ip_city. null when the IP has no city record yet (cron backfill in flight) or the row is loopback.

One of 2:

Variant 1

citystring | nullRequired

One of 2:

Variant 1

string

City name (brj__geo_ip_city.city).

Variant 2

null

countryNamestring | nullRequired

One of 2:

Variant 1

string

Country name (brj__geo_ip_city.country).

Variant 2

null

countryCodestring | nullRequired

One of 2:

Variant 1

string

ISO-3166-1 alpha-2 country code derived from countryName via formatCountryCode. Kept on the wire so the admin grid can pick a flag emoji without shipping a name→code map to the client.

Variant 2

null

Variant 2

null

itemCountnumberRequired

Total matching issues (for pagination).

Response example

application/json

{
  "items": [
    {
      "id": "example_id",
      "internalId": 0,
      "issueKey": "example_issueKey",
      "subject": "example_subject",
      "priority": 0,
      "priorityLabel": "example_priorityLabel",
      "velocity": 0,
      "type": {
        "id": 0,
        "code": "example_code"
      },
      "status": {
        "id": 0,
        "label": "example_label",
        "categoryId": 0,
        "categoryCode": "example_categoryCode"
      },
      "securedTicket": false,
      "commentsCount": 0,
      "hasAttachments": false,
      "isStale": false
    }
  ],
  "itemCount": 0
}

Request example

GET /bff/issue/list

get

curl -X GET "https://api.bizkithub.com/bff/issue/list?projectCode=PROJ&statusCategoryId=1&statusCategoryCode=active&statusId=42&assigneeId=10&unassigned=false&assigneeFilter=me&reporterId=5&priority=3&isSpam=false&securedOnly=false&contactExternalId=1JfEq22KdM3B456i&orderBy=smart%3Aasc&page=1&limit=50" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key