Issue

To learn about issues, check the Issues page.

Get

Get a single Issue.

GET /api/1/issue/$issue_id

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

Example of response:

{
    "id": 1,
    "kind": {
        "id": 1,
        "description": "Kernel bug",
        "tag": "Kernel Bug"
    },
    "description": "Bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "resolved": false,
    "resolved_at": null,
    "policy": {
        "id": 1,
        "name": "public"
    },
    "first_seen": "2022-03-16T08:55:51.749000Z",
    "last_seen": "2022-04-16T10:23:45.123000Z",
    "last_edited_at": "2022-04-16T10:23:45.123000Z",
    "upstream_status_description": null,
    "upstream_last_activity_at": null,
    "tags": [],
    "regexes": []
}

List

Get a list of Issues.

GET /api/1/issue

Name	Type	Required	Description
`resolved`	`bool`	No	Filter resolved or not resolved issues.
`kind`	`int`	No	Filter issues with specific issue kind id.

Example of response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "kind": {
                "id": 1,
                "description": "Kernel bug",
                "tag": "Kernel Bug"
            },
            "description": "Bug description.",
            "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
            "resolved": false,
            "resolved_at": null,
            "policy": {
                "id": 1,
                "name": "public"
            },
            "first_seen": "2022-03-16T08:55:51.749000Z",
            "last_seen": "2022-04-16T10:23:45.123000Z",
            "last_edited_at": "2022-04-16T10:23:45.123000Z",
            "upstream_status_description": null,
            "upstream_last_activity_at": null,
            "tags": [],
            "regexes": []
        }
    ]
}

Create

Create a new Issue. (Auth Required)

POST /api/1/issue

Request body should contain JSON with issue data:

{
    "kind": 1,
    "description": "Bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "policy": 1,
    "upstream_status_description": "NEW",
    "tags": []
}

Field	Type	Required	Description
`kind`	`int`	Yes	ID of the Issue Kind.
`description`	`string`	Yes	Description of the issue.
`ticket_url`	`string`	Yes	URL to the ticket (must be unique).
`policy`	`int`	Yes	ID of the policy.
`upstream_status_description`	`string`	No	Upstream status description.
`upstream_last_activity_at`	`string`	No	ISO datetime of last upstream activity.
`tags`	`array`	No	Array of tag strings.

Example of response:

{
    "id": 2,
    "kind": {
        "id": 1,
        "description": "Kernel bug",
        "tag": "Kernel Bug"
    },
    "description": "Bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "resolved": false,
    "resolved_at": null,
    "policy": {
        "id": 1,
        "name": "public"
    },
    "first_seen": null,
    "last_seen": null,
    "last_edited_at": "2022-04-16T10:23:45.123000Z",
    "upstream_status_description": "NEW",
    "upstream_last_activity_at": null,
    "tags": [],
    "regexes": []
}

Delete

Delete a single issue. (Auth Required)

DELETE /api/1/issue/$issue_id

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

Responds with 204 and empty content.

Partial Update

Update only some fields of a single issue. (Auth Required)

PATCH /api/1/issue/$issue_id

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

Request body should contain JSON with fields to update:

{
    "description": "Updated bug description.",
    "upstream_status_description": "RESOLVED",
    "tags": ["VERIFIED_WONTFIX"]
}

Fields that can be updated:

kind (int): Issue kind ID
description (string): Issue description
ticket_url (string): Ticket URL (must be unique)
resolved_at (string): ISO datetime when issue was resolved (null to mark as unresolved)
upstream_status_description (string): Upstream status
upstream_last_activity_at (string): ISO datetime of last upstream activity
tags (array): Array of tag strings
policy (int): Policy ID

Example response (returns the updated issue object with full data):

{
    "id": 1,
    "kind": {
        "id": 1,
        "description": "Kernel bug",
        "tag": "Kernel Bug"
    },
    "description": "Updated bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "resolved": false,
    "resolved_at": null,
    "policy": {
        "id": 1,
        "name": "public"
    },
    "first_seen": "2022-03-16T08:55:51.749000Z",
    "last_seen": "2022-04-16T10:23:45.123000Z",
    "last_edited_at": "2022-04-16T11:45:30.456000Z",
    "upstream_status_description": "RESOLVED",
    "upstream_last_activity_at": null,
    "tags": ["VERIFIED_WONTFIX"],
    "regexes": []
}

Full Update

Completely replace a single issue. (Auth Required)

PUT /api/1/issue/$issue_id

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

Request body must contain JSON with all required fields:

{
    "kind": 1,
    "description": "Completely updated bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "policy": 1,
    "upstream_status_description": "RESOLVED",
    "upstream_last_activity_at": "2022-04-16T10:30:00.000000Z",
    "tags": []
}

Example response (returns the updated issue object with full data):

{
    "id": 1,
    "kind": {
        "id": 1,
        "description": "Kernel bug",
        "tag": "Kernel Bug"
    },
    "description": "Completely updated bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
    "resolved": false,
    "resolved_at": null,
    "policy": {
        "id": 1,
        "name": "public"
    },
    "first_seen": "2022-03-16T08:55:51.749000Z",
    "last_seen": "2022-04-16T10:23:45.123000Z",
    "last_edited_at": "2022-04-16T11:50:15.789000Z",
    "upstream_status_description": "RESOLVED",
    "upstream_last_activity_at": "2022-04-16T10:30:00.000000Z",
    "tags": [],
    "regexes": []
}

Top Issues

Get top issues ordered by hit count within a date range. Issues are ranked by the number of unique checkouts where they occurred.

GET /api/1/issue/top

Name	Type	Required	Description
`date_from`	`string`	No	Start date for filtering (ISO datetime or timestamp).
`date_to`	`string`	No	End date for filtering (ISO datetime or timestamp).

Example request: GET /api/1/issue/top?date_from=2022-01-01T00:00:00Z&date_to=2022-12-31T23:59:59Z

Example of response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "kind": {
                "id": 1,
                "description": "Kernel bug",
                "tag": "Kernel Bug"
            },
            "description": "Most common bug description.",
            "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
            "resolved": false,
            "resolved_at": null,
            "policy": {
                "id": 1,
                "name": "public"
            },
            "first_seen": "2022-03-16T08:55:51.749000Z",
            "last_seen": "2022-04-16T10:23:45.123000Z",
            "last_edited_at": "2022-04-16T10:23:45.123000Z",
            "upstream_status_description": null,
            "upstream_last_activity_at": null,
            "tags": [],
            "regexes": [],
            "hit_count": 15
        },
        {
            "id": 2,
            "kind": {
                "id": 2,
                "description": "Unstable Test",
                "tag": "Unstable Test"
            },
            "description": "Second most common issue.",
            "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=654321",
            "resolved": false,
            "resolved_at": null,
            "policy": {
                "id": 1,
                "name": "public"
            },
            "first_seen": "2022-02-10T14:22:30.456000Z",
            "last_seen": "2022-04-15T16:45:12.789000Z",
            "last_edited_at": "2022-04-15T16:45:12.789000Z",
            "upstream_status_description": "NEW",
            "upstream_last_activity_at": "2022-04-15T16:30:00.000000Z",
            "tags": [],
            "regexes": [],
            "hit_count": 8
        }
    ]
}

List Checkouts

Get KCIDB checkouts where the issue has occurred. Results are filtered by the caller’s authorization on checkout policy.

GET /api/1/issue/$issue_id/checkouts

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

Example of response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "iid": 137,
            "id": "b8fba93561c984f336d47d6d544be3a2a920bac3",
            "tree_name": "upstream",
            "git_repository_branch": "queue/5.7",
            "git_commit_hash": "b8fba93561c984f336d47d6d544be3a2a920bac3",
            "kernel_version": "5.14.0-162.el9",
            "start_time": "2020-06-30T17:06:26.357000Z"
        }
    ]
}

Attach Checkouts

Attach one or more existing KCIDB checkouts to the issue, creating an IssueOccurrence for each one. (Auth Required: add_issueoccurrence permission and write access to the issue)

POST /api/1/issue/$issue_id/checkouts

Name	Type	Required	Description
`issue_id`	`int`	Yes	ID of the Issue.

{
    "checkout_ids": ["redhat:123456"]
}

Example of response (array of created IssueOccurrences, see IssueOccurrence Get):

[
    {
        "issue": {"id": 1, "...": "..."},
        "is_regression": false,
        "created_at": "2022-04-14T05:33:09.415318Z",
        "checkout_id": "redhat:123456",
        "build_id": null,
        "test_id": null,
        "testresult_id": null
    }
]

Attaching a checkout that is already linked to the issue is idempotent and returns the existing occurrence instead of an error.

Attach Builds

Attach one or more existing KCIDB builds to the issue. Same behavior as Attach Checkouts, using build_ids in the request body.

POST /api/1/issue/$issue_id/builds

{
    "build_ids": ["redhat:926214"]
}

Attach Tests

Attach one or more existing KCIDB tests to the issue. Same behavior as Attach Checkouts, using test_ids in the request body.

POST /api/1/issue/$issue_id/tests

{
    "test_ids": ["redhat:112448273"]
}

Attach Test Results

Attach one or more existing KCIDB test results to the issue. Same behavior as Attach Checkouts, using testresult_ids in the request body.

POST /api/1/issue/$issue_id/testresults

{
    "testresult_ids": ["redhat:112448273_0"]
}

OPTIONS Requests

All /issue endpoints support OPTIONS requests that return allowed HTTP methods and other metadata:

OPTIONS /api/1/issue
OPTIONS /api/1/issue/$issue_id
OPTIONS /api/1/issue/top
OPTIONS /api/1/issue/$issue_id/checkouts
OPTIONS /api/1/issue/$issue_id/builds
OPTIONS /api/1/issue/$issue_id/tests
OPTIONS /api/1/issue/$issue_id/testresults

Example OPTIONS response:

{
    "name": "Issue List",
    "description": "ViewSet for Issues.",
    "renders": [
        "application/json",
        "text/html"
    ],
    "parses": [
        "application/json",
        "application/x-www-form-urlencoded",
        "multipart/form-data"
    ],
    "actions": {
        "POST": {
            "kind": {
                "type": "field",
                "required": true
            },
            "description": {
                "type": "string",
                "required": true
            }
        }
    }
}

Get IssueOccurrence for a KCIDB Object

Get a single IssueOccurrence related to a KCIDB object.

GET /api/1/kcidb/$object/issues/occurrences/$issue_id

Name	Type	Required	Description
`object`	`str`	Yes	Name of the KCIDB object: checkout, build, test or testresult.
`issue_id`	`int`	Yes	ID of the Issue.

Example of response:

{
    "issue": {
        "id": 1075,
        "kind": {
            "id": 3,
            "description": "Unstable Test",
            "tag": "Unstable Test"
        },
        "description": "LTP - syscalls: waitid10.c:36: TFAIL: infop->si_status (0) != SIGFPE (8)",
        "ticket_url": "https://lists.linux.it/pipermail/ltp/2022-March/028110.html",
        "resolved": false,
        "resolved_at": null,
        "policy": {
            "id": 1,
            "name": "public"
        },
        "first_seen": "2022-03-16T08:55:51.749000Z"
    },
    "is_regression": false,
    "created_at": "2022-04-14T05:33:09.415318Z"
}

List IssueOccurrences for a KCIDB Object

Get all IssueOccurrences related to a KCIDB object.

GET /api/1/kcidb/$object/issues/occurrences

Name	Type	Required	Description
`object`	`str`	Yes	Name of the KCIDB object: checkout, build, test or testresult.

Example of response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "issue": {
                "id": 1075,
                "kind": {
                    "id": 3,
                    "description": "Unstable Test",
                    "tag": "Unstable Test"
                },
                "description": "LTP - syscalls: waitid10.c:36: TFAIL: infop->si_status (0) != SIGFPE (8)",
                "ticket_url": "https://lists.linux.it/pipermail/ltp/2022-March/028110.html",
                "resolved": false,
                "resolved_at": null,
                "policy": {
                    "id": 1,
                    "name": "public"
                },
                "first_seen": "2022-03-16T08:55:51.749000Z"
            },
            "is_regression": false,
            "created_at": "2022-04-14T05:33:09.415318Z"
        }
    ]
}

Create IssueOccurrences for a KCIDB Object

Link an Issue to a KCIDB object.

POST /api/1/kcidb/$object/issues

Name	Type	Required	Description
`object`	`str`	Yes	Name of the KCIDB object: checkout, build, test or testresult.
`issue_id`	`int`	Yes	ID of the Issue.

Example of response:

{
    "id": 1,
    "kind": {
        "id": 1,
        "description": "Kernel bug",
        "tag": "Kernel Bug"
    },
    "description": "Bug description.",
    "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456"
    "resolved": false,
},