Skip to content

Bandum API (runs on your machine): board ​

Repos, milestones (sprints) and tasks by status

This page is generated from openapi.yaml by npm run gen, so do not edit it by hand. Authentication is described on the overview page.

GET/v1/repos

Tracked repos, milestones and sync status

Responses ​

CodeDescriptionType
200Repos in the order listed in BANDUM_REPOSapplication/json · object[]
401Not signed inapplication/problem+json · object

Example response ​

json
[
  {
    "project": "shop-web",
    "taskSource": "scm",
    "scmConnected": false,
    "scmReason": "scm_connection_required",
    "fullName": "your-org/your-project",
    "url": "string",
    "milestones": [
      {}
    ]
  }
]

Call with curl ​

bash
curl "http://localhost:8070/v1/repos" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
GET/v1/board

Tasks of a repo, filtered by milestone

Without milestone: every open issue plus issues closed in the last 14 days. With milestone: every issue of that milestone (including closed ones).

Parameters ​

NameInTypeRequiredDescription
repoquerystringyesowner/repo; must be linked to a project of the organization
milestonequerystringMilestone (sprint) name

Responses ​

CodeDescriptionType
200Boardapplication/json · object
400Invalid parameterapplication/problem+json · object
401Not signed inapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "repo": "string",
  "milestone": {
    "number": 0,
    "title": "string",
    "state": "open",
    "dueOn": "2026-11-01T00:00:00Z",
    "openTasks": 0,
    "closedTasks": 0
  },
  "readyForRelease": false,
  "syncedAt": "2026-11-01T00:00:00Z",
  "tasks": [
    {
      "repo": "string",
      "number": 0,
      "key": "GH-12",
      "taskSource": "scm",
      "title": "string",
      "url": "string",
      "status": "todo",
      "assignees": [],
      "level": "S",
      "testcaseCount": 0
    }
  ]
}

Call with curl ​

bash
curl "http://localhost:8070/v1/board?repo=string" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
GET/v1/inbox

My inbox, the tasks waiting for me

Computed from what the mirror already holds, across every repo of the organization. "Me" is the signed-in login; online it also matches the connected source-control account, in local mode it is the user of the local instance. toTest: status review, open PR, I am not an assignee, and I am a named tester (label tester: <login>) or no tester is named. resubmitted: I sent it back in the latest run and the developer handed it in again (status review). sentBack: my task (I am an assignee) in status rejected. Each task is in at most one list; the oldest comes first.

Responses ​

CodeDescriptionType
200Inboxapplication/json · object
401Not signed inapplication/problem+json · object
403Not allowed with this role, or the token or session has no organizationapplication/problem+json · object

Example response ​

json
{
  "login": "string",
  "count": 0,
  "toTest": [
    {
      "repo": "string",
      "number": 0,
      "key": "GH-12",
      "taskSource": "scm",
      "title": "string",
      "url": "string",
      "status": "todo",
      "assignees": [],
      "level": "S",
      "testcaseCount": 0
    }
  ],
  "resubmitted": [
    {
      "repo": "string",
      "number": 0,
      "key": "GH-12",
      "taskSource": "scm",
      "title": "string",
      "url": "string",
      "status": "todo",
      "assignees": [],
      "level": "S",
      "testcaseCount": 0
    }
  ],
  "sentBack": [
    {
      "repo": "string",
      "number": 0,
      "key": "GH-12",
      "taskSource": "scm",
      "title": "string",
      "url": "string",
      "status": "todo",
      "assignees": [],
      "level": "S",
      "testcaseCount": 0
    }
  ]
}

Call with curl ​

bash
curl "http://localhost:8070/v1/inbox" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
GET/v1/tasks/{owner}/{repo}/{number}

Task details, status history and test runs

Parameters ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
numberpathintegeryes

Responses ​

CodeDescriptionType
200Taskapplication/json · object + object
401Not signed inapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "repo": "string",
  "number": 0,
  "key": "GH-12",
  "taskSource": "scm",
  "title": "string",
  "url": "string",
  "status": "todo",
  "assignees": [
    "string"
  ],
  "level": "S",
  "testcaseCount": 0,
  "acceptancePath": "string",
  "stagingUrl": "string",
  "previewUrl": "string",
  "stagingVersion": {
    "state": "match",
    "commit": "string",
    "prCommit": "string",
    "error": "blocked"
  },
  "history": [
    {
      "at": "2026-11-01T00:00:00Z",
      "status": "todo",
      "actor": "string"
    }
  ],
  "testcases": [
    {
      "id": "string",
      "acs": [],
      "title": "string"
    }
  ],
  "runs": [
    {
      "index": 0,
      "approved": false,
      "total": 0,
      "failed": 0,
      "tester": "string",
      "commit": "string",
      "note": "string",
      "results": []
    }
  ],
  "metrics": {
    "repo": "string",
    "number": 0,
    "key": "string",
    "title": "string",
    "status": "todo",
    "level": "S",
    "runs": 0,
    "rejections": 0
  }
}

Call with curl ​

bash
curl "http://localhost:8070/v1/tasks/<owner>/<repo>/<number>" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
POST/v1/tasks/{owner}/{repo}/{number}/acceptance

Record manual testing results (Approve / Send back)

Adds a test run to acceptance.md on the PR branch (same format that ph bandum test writes), reviews the PR and changes the label (approved when every test case passes, otherwise rejected), using the GitHub account of the signed-in web user. Every test case in testcases.md at the PR head commit must be graded.

Parameters ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
numberpathintegeryes

Body (application/json) ​

FieldTypeRequiredDescription
notestringGeneral note
commitstringPR head commit the tester ran (from the task page); if it differs from the current commit, the server returns 409
resultsobject[]yes

Responses ​

CodeDescriptionType
201Test run recorded. For a tracker task writeBack tells whether the tracker was updated too (a failed write-back does not undo the recorded run)application/json · object + object + object
400Invalid parameterapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Cannot record with the current identity (Tara token, or a session without GitHub write access)application/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object
409The PR branch just changed (new commit, or someone else recorded a result); reload and grade againapplication/problem+json · object

Example response ​

json
{
  "index": 0,
  "approved": false,
  "total": 0,
  "failed": 0,
  "tester": "string",
  "commit": "string",
  "note": "string",
  "results": [
    {
      "id": "TC-3",
      "acs": [],
      "passed": false,
      "note": "string"
    }
  ],
  "writeBack": {
    "ok": false,
    "skipped": false,
    "commented": false,
    "error": "string"
  }
}

Call with curl ​

bash
curl -X POST "http://localhost:8070/v1/tasks/<owner>/<repo>/<number>/acceptance" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"string","commit":"string","results":[{"id":"TC-1","passed":false,"note":"string"}]}'
POST/v1/tasks/{owner}/{repo}/{number}/sync-status

Retry writing the latest test result back to the task tracker (tracker tasks only)

Reads the latest run of acceptance.md on the PR branch and writes it to the tracker with the signed-in user's tracker token: a transition to approved or rejected (skipped when the task is already there) and a summary comment (Bandum acceptance run N: …). When the tracker already shows the run's status and the transition is skipped, the run counts as already written and no second comment is posted. Always HTTP 200; ok: false carries the reason when the tracker still refuses. For a GitHub/GitLab task it answers 400.

Parameters ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
numberpathintegeryes

Responses ​

CodeDescriptionType
200Result of the write-backapplication/json · object
400Invalid parameterapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Cannot write with the current identityapplication/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object

Example response ​

json
{
  "ok": false,
  "skipped": false,
  "commented": false,
  "error": "string"
}

Call with curl ​

bash
curl -X POST "http://localhost:8070/v1/tasks/<owner>/<repo>/<number>/sync-status" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY"
POST/v1/tasks/{owner}/{repo}/{number}/bugs

Report an out-of-scope bug (new issue, or a comment if it is a duplicate)

Creates a type: bug issue with the connected account of the signed-in web user (local mode: the token from the BANDUM_SCM_TOKEN_CMD command), using the same format and duplicate check as ph bandum bug: task number is where the bug was found (--from); the reporter, commit and branch come from the task's PR if there is one. A duplicate (same normalized title and task, issue still open) does not create a new issue; it adds a "Seen again." comment to the existing issue (duplicate: true). Secrets in the title and body are masked before sending. A bug in the task under test is graded as a "Fail" test case instead; do not use this endpoint for it. If owner has several segments (GitLab subgroups), encode / as %2F.

Parameters ​

NameInTypeRequiredDescription
ownerpathstringyes
repopathstringyes
numberpathintegeryes

Body (application/json) ​

FieldTypeRequiredDescription
titlestringyes
stepsstringSteps to reproduce
expectedstringExpected
actualstringActual
severityhigh | medium | lowOld values cao, trung-binh and thap are still accepted as aliases for high, medium and low
tcstringRelated test case
assigneesstring[]Assignee logins; ignored by older kits that do not support assigning

Responses ​

CodeDescriptionType
201Issue created, or comment added to the existing issueapplication/json · object
400Invalid parameterapplication/problem+json · object
401Not signed inapplication/problem+json · object
403Cannot report with the current identity (Tara token, account not connected, or the account cannot create issues)application/problem+json · object
404Repo, milestone, task or organization not foundapplication/problem+json · object
422The scm kit in use has no report capability group; upgrade kit-scm-*application/problem+json · object

Example response ​

json
{
  "number": 0,
  "url": "string",
  "duplicate": false
}

Call with curl ​

bash
curl -X POST "http://localhost:8070/v1/tasks/<owner>/<repo>/<number>/bugs" \
  -H "Authorization: Bearer $BANDUM_LOCAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","steps":"string","expected":"string","actual":"string"}'