GitLab CI/CD issues API

openapi: 3.2.0
info:
  title: GitLab access_requests Issues API
  version: v4
  description: Operations related to access requests
servers:
- url: https://gitlab.com
tags:
- name: issues
  description: Operations about issues
paths:
  /api/v4/projects/{id}/issues/{issue_iid}/links:
    get:
      summary: List issue relations
      description: Get a list of a given issue’s linked issues, sorted by the relationship creation datetime (ascending).Issues are filtered according to the user authorizations.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project’s issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List issue relations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/API_Entities_RelatedIssue'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidLinks
    post:
      summary: Create an issue link
      description: Creates a two-way relation between two issues.The user must be allowed to update both issues to succeed.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project’s issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Create an issue link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssueLink'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      tags:
      - issues
      operationId: postApiV4ProjectsIdIssuesIssueIidLinks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdIssuesIssueIidLinks'
        required: true
  /api/v4/projects/{id}/issues/{issue_iid}/links/{issue_link_id}:
    get:
      summary: Get an issue link
      description: Gets details about an issue link. This feature was introduced in GitLab 15.1.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project’s issue
        required: true
        schema:
          type: integer
          format: int32
      - in: path
        name: issue_link_id
        description: ID of an issue relationship
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Get an issue link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssueLink'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidLinksIssueLinkId
    delete:
      summary: Delete an issue link
      description: Deletes an issue link, thus removes the two-way relationship.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project owned by the authenticated user
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project’s issue
        required: true
        schema:
          type: integer
          format: int32
      - in: path
        name: issue_link_id
        description: The ID of an issue relationship
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
        '204':
          description: Delete an issue link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssueLink'
        '404':
          description: Not found
      tags:
      - issues
      operationId: deleteApiV4ProjectsIdIssuesIssueIidLinksIssueLinkId
  /api/v4/projects/{id}/issues/{issue_iid}/time_estimate:
    post:
      summary: Set a time estimate for a issue
      description: Sets an estimated time of work for this issue.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of the issue.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Set a time estimate for a issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssuableTimeStats'
        '401':
          description: Unauthorized
        '400':
          description: Bad request
        '404':
          description: Not found
      tags:
      - issues
      operationId: postApiV4ProjectsIdIssuesIssueIidTimeEstimate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdIssuesIssueIidTimeEstimate'
        required: true
  /api/v4/projects/{id}/issues/{issue_iid}/reset_time_estimate:
    post:
      summary: Reset the time estimate for a project issue
      description: Resets the estimated time for this issue to 0 seconds.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of the issue.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Reset the time estimate for a project issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssuableTimeStats'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: postApiV4ProjectsIdIssuesIssueIidResetTimeEstimate
  /api/v4/projects/{id}/issues/{issue_iid}/add_spent_time:
    post:
      summary: Add spent time for a issue
      description: Adds spent time for this issue.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of the issue.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Add spent time for a issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssuableTimeStats'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: postApiV4ProjectsIdIssuesIssueIidAddSpentTime
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdIssuesIssueIidAddSpentTime'
        required: true
  /api/v4/projects/{id}/issues/{issue_iid}/reset_spent_time:
    post:
      summary: Reset spent time for a issue
      description: Resets the total spent time for this issue to 0 seconds.
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of the issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Reset spent time for a issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssuableTimeStats'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: postApiV4ProjectsIdIssuesIssueIidResetSpentTime
  /api/v4/projects/{id}/issues/{issue_iid}/time_stats:
    get:
      summary: Get time tracking stats
      description: Get time tracking stats
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of the issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get time tracking stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_IssuableTimeStats'
        '401':
          description: Unauthorized
        '404':
          description: Not found
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidTimeStats
  /api/v4/projects/{id}/issues/{issue_iid}/related_merge_requests:
    get:
      description: List merge requests that are related to the issue
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List merge requests that are related to the issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_MergeRequestBasic'
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidRelatedMergeRequests
  /api/v4/projects/{id}/issues/{issue_iid}/participants:
    get:
      description: List participants for an issue
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List participants for an issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_UserBasic'
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidParticipants
  /api/v4/projects/{id}/issues/{issue_iid}/user_agent_detail:
    get:
      description: Get the user agent details for an issue
      parameters:
      - in: path
        name: id
        description: The ID or URL-encoded path of the project
        required: true
        schema:
          type: string
      - in: path
        name: issue_iid
        description: The internal ID of a project issue
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get the user agent details for an issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_UserAgentDetail'
      tags:
      - issues
      operationId: getApiV4ProjectsIdIssuesIssueIidUserAgentDetail
  /api/v4/issues:
    get:
      description: Get currently authenticated user's issues
      parameters:
      - in: query
        name: with_labels_details
        description: Return titles of labels and other details
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: state
        description: Return opened, closed, or all issues
        required: false
        schema:
          type: string
          enum:
          - opened
          - closed
          - all
          default: all
      - in: query
        name: closed_by_id
        description: Return issues which were closed by the user with the given ID.
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: order_by
        description: Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, or `updated_at` fields.
        required: false
        schema:
          type: string
          enum:
          - created_at
          - due_date
          - label_priority
          - milestone_due
          - popularity
          - priority
          - relative_position
          - title
          - updated_at
          - weight
          default: created_at
      - in: query
        name: sort
        description: Return issues sorted in `asc` or `desc` order.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: due_date
        description: 'Return issues that have no due date (`0`), or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`, `0`'
        required: false
        schema:
          type: string
          enum:
          - '0'
          - any
          - today
          - tomorrow
          - overdue
          - week
          - month
          - next_month_and_previous_two_weeks
          - ''
      - in: query
        name: issue_type
        description: 'The type of the issue. Accepts: issue, incident, test_case, requirement, task, ticket'
        required: false
        schema:
          type: string
          enum:
          - issue
          - incident
          - test_case
          - requirement
          - task
          - ticket
      - in: query
        name: labels
        description: Comma-separated list of label names
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: milestone
        description: Milestone title
        required: false
        schema:
          type: string
      - in: query
        name: milestone_id
        description: Return issues assigned to milestones with the specified timebox value ("Any", "None", "Upcoming" or "Started")
        required: false
        schema:
          type: string
          enum:
          - Any
          - None
          - Upcoming
          - Started
      - in: query
        name: iids
        description: The IID array of issues
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: search
        description: Search issues for text present in the title, description, or any combination of these
        required: false
        schema:
          type: string
      - in: query
        name: in
        description: '`title`, `description`, or a string joining them with comma'
        required: false
        schema:
          type: string
      - in: query
        name: author_id
        description: Return issues which are authored by the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: author_username
        description: Return issues which are authored by the user with the given username
        required: false
        schema:
          type: string
      - in: query
        name: assignee_id
        description: Return issues which are assigned to the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: assignee_username
        description: Return issues which are assigned to the user with the given username
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: created_after
        description: Return issues created after the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: created_before
        description: Return issues created before the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_after
        description: Return issues updated after the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_before
        description: Return issues updated before the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: not[labels]
        description: Comma-separated list of label names
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: not[milestone]
        description: Milestone title
        required: false
        schema:
          type: string
      - in: query
        name: not[milestone_id]
        description: Return issues assigned to milestones without the specified timebox value ("Any", "None", "Upcoming" or "Started")
        required: false
        schema:
          type: string
          enum:
          - Any
          - None
          - Upcoming
          - Started
      - in: query
        name: not[iids]
        description: The IID array of issues
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: not[author_id]
        description: Return issues which are not authored by the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[author_username]
        description: Return issues which are not authored by the user with the given username
        required: false
        schema:
          type: string
      - in: query
        name: not[assignee_id]
        description: Return issues which are not assigned to the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[assignee_username]
        description: Return issues which are not assigned to the user with the given username
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: not[weight]
        description: Return issues without the specified weight
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[iteration_id]
        description: Return issues which are not assigned to the iteration with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[iteration_title]
        description: Return issues which are not assigned to the iteration with the given title
        required: false
        schema:
          type: string
      - in: query
        name: scope
        description: 'Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`'
        required: false
        schema:
          type: string
          enum:
          - created-by-me
          - assigned-to-me
          - created_by_me
          - assigned_to_me
          - all
          default: created_by_me
      - in: query
        name: my_reaction_emoji
        description: Return issues reacted by the authenticated user by the given emoji
        required: false
        schema:
          type: string
      - in: query
        name: confidential
        description: Filter confidential or public issues
        required: false
        schema:
          type: boolean
      - in: query
        name: weight
        description: The weight of the issue
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: epic_id
        description: The ID of an epic associated with the issues
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: health_status
        description: 'The health status of the issue. Must be one of: on_track, needs_attention, at_risk, none, any'
        required: false
        schema:
          type: string
          enum:
          - on_track
          - needs_attention
          - at_risk
          - none
          - any
      - in: query
        name: iteration_id
        description: Return issues which are assigned to the iteration with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: iteration_title
        description: Return issues which are assigned to the iteration with the given title
        required: false
        schema:
          type: string
      - in: query
        name: page
        description: Current page number
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of items per page
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          default: 20
      - in: query
        name: non_archived
        description: Return issues from non archived projects
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Get currently authenticated user's issues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Issue'
      tags:
      - issues
      operationId: getApiV4Issues
  /api/v4/issues/{id}:
    get:
      description: Get specified issue (admin only)
      parameters:
      - in: path
        name: id
        description: The ID of the Issue
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Get specified issue (admin only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Entities_Issue'
      tags:
      - issues
      operationId: getApiV4IssuesId
  /api/v4/issues_statistics:
    get:
      description: Get currently authenticated user's issues statistics
      parameters:
      - in: query
        name: labels
        description: Comma-separated list of label names
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: milestone
        description: Milestone title
        required: false
        schema:
          type: string
      - in: query
        name: milestone_id
        description: Return issues assigned to milestones with the specified timebox value ("Any", "None", "Upcoming" or "Started")
        required: false
        schema:
          type: string
          enum:
          - Any
          - None
          - Upcoming
          - Started
      - in: query
        name: iids
        description: The IID array of issues
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: search
        description: Search issues for text present in the title, description, or any combination of these
        required: false
        schema:
          type: string
      - in: query
        name: in
        description: '`title`, `description`, or a string joining them with comma'
        required: false
        schema:
          type: string
      - in: query
        name: author_id
        description: Return issues which are authored by the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: author_username
        description: Return issues which are authored by the user with the given username
        required: false
        schema:
          type: string
      - in: query
        name: assignee_id
        description: Return issues which are assigned to the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: assignee_username
        description: Return issues which are assigned to the user with the given username
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: created_after
        description: Return issues created after the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: created_before
        description: Return issues created before the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_after
        description: Return issues updated after the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_before
        description: Return issues updated before the specified time
        required: false
        schema:
          type: string
          format: date-time
      - in: query
        name: not[labels]
        description: Comma-separated list of label names
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: not[milestone]
        description: Milestone title
        required: false
        schema:
          type: string
      - in: query
        name: not[milestone_id]
        description: Return issues assigned to milestones without the specified timebox value ("Any", "None", "Upcoming" or "Started")
        required: false
        schema:
          type: string
          enum:
          - Any
          - None
          - Upcoming
          - Started
      - in: query
        name: not[iids]
        description: The IID array of issues
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - in: query
        name: not[author_id]
        description: Return issues which are not authored by the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[author_username]
        description: Return issues which are not authored by the user with the given username
        required: false
        schema:
          type: string
      - in: query
        name: not[assignee_id]
        description: Return issues which are not assigned to the user with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[assignee_username]
        description: Return issues which are not assigned to the user with the given username
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: not[weight]
        description: Return issues without the specified weight
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[iteration_id]
        description: Return issues which are not assigned to the iteration with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: not[iteration_title]
        description: Return issues which are not assigned to the iteration with the given title
        required: false
        schema:
          type: string
      - in: query
        name: scope
        description: 'Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`'
        required: false
        schema:
          type: string
          enum:
          - created_by_me
          - assigned_to_me
          - all
          default: created_by_me
      - in: query
        name: my_reaction_emoji
        description: Return issues reacted by the authenticated user by the given emoji
        required: false
        schema:
          type: string
      - in: query
        name: confidential
        description: Filter confidential or public issues
        required: false
        schema:
          type: boolean
      - in: query
        name: weight
        description: The weight of the issue
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: epic_id
        description: The ID of an epic associated with the issues
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: health_status
        description: 'The health status of the issue. Must be one of: on_track, needs_attention, at_risk, none, any'
        required: false
        schema:
          type: string
          enum:
          - on_track
          - needs_attention
          - at_risk
          - none
          - any
      - in: query
        name: iteration_id
        description: Return issues which are assigned to the iteration with the given ID
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: iteration_title
        description: Return issues which are assigned to the iteration with the given title
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Get currently authenticated user's issues statistics
      tags:
      - issues
      operationId: getApiV4IssuesStatistics
components:
  schemas:
    API_Entities_IssuableReferences:
      type: object
      properties:
        short:
          type: string
          example: '&6'
        relative:
          type: string
          example: '&6'
        full:
          type: string
          example: test&6
      required:
      - short
      - relative
      - full
    EpicBaseEntity:
      type: object
      properties:
        id:
          type: string
        iid:
          type: string
        title:
          type: string
        url:
          type: string
        group_id:
          type: string
        human_readable_end_date:
          type: string
        human_readable_timestamp:
          type: string
      required:
      - id
      - iid
      - title
      - url
      - group_id
    API_Entities_IssueLink:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        source_issue:
          $ref: '#/components/schemas/API_Entities_IssueBasic'
        target_issue:
          $ref: '#/components/schemas/API_Entities_IssueBasic'
        link_type:
          type: string
          example: relates_to
      required:
      - id
      - source_issue
      - target_issue
      - link_type
      description: API_Entities_IssueLink model
    API_Entities_IssuableTimeStats:
      type: object
      properties:
        time_estimate:
          type: integer
          format: int32
          example: 12600
     

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-issues-api-openapi.yml