GitLab Events API

openapi: 3.2.0
info:
  title: GitLab REST Events API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Events
  description: 'Use this API to review event activity for a user, a project, or an instance. Events cover a wide

    range of actions, such as joining a project, commenting on an issue, pushing changes to a merge

    request, or closing an epic.


    Activity is subject to retention limits. For more information, see the

    user activity time period limit

    and the project activity time period limit.


    These endpoints have some limitations:


    - Some epic features, such as child items, linked items, start dates, due dates, and health statuses, are not returned.

    - Some merge request notes use the `DiscussionNote` type instead, which is not supported.

    - Bulk push events, created when a push exceeds the push event activities limit, are returned with limited details.'
  x-displayName: Events
  externalDocs:
    url: https://docs.gitlab.com/api/events/
paths:
  /api/v4/projects/{id}/events:
    get:
      operationId: getApiV4ProjectsIdEvents
      summary: List all visible events for a project
      description: 'Lists all visible events for a specified project. When a push exceeds the Push event activities limit, a single bulk push event is returned instead of individual commit events. Bulk push events have limited commit details: `commit_count` is `0`, `ref_count` shows the number of refs pushed, and individual commit attributes are `null`.'
      tags:
      - Events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesEvent'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: action
        required: false
        description: Filter events by the specified [action type](https://docs.gitlab.com/user/profile/contributions_calendar/#user-contribution-events).
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_type
        required: false
        description: Filter events by target type.
        schema:
          type:
          - string
          - 'null'
          enum:
          - issue
          - milestone
          - merge_request
          - note
          - project
          - snippet
          - user
          - wiki
          - design
          - null
        in: query
      - name: before
        required: false
        description: Return events created before the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: after
        required: false
        description: Return events created after the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: sort
        required: false
        description: Sort results in ascending or descending order by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
  /api/v4/events:
    get:
      operationId: getApiV4Events
      summary: List all events
      description: Lists all events for the authenticated user. Does not return events associated with epics or merge requests. Returns bulk push events with limited commit details.
      tags:
      - Events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesEvent'
        '401':
          description: Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: scope
        required: false
        description: Include all events across the user's projects.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: all
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      - name: action
        required: false
        description: Filter events by the specified [action type](https://docs.gitlab.com/user/profile/contributions_calendar/#user-contribution-events).
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_type
        required: false
        description: Filter events by target type.
        schema:
          type:
          - string
          - 'null'
          enum:
          - issue
          - milestone
          - merge_request
          - note
          - project
          - snippet
          - user
          - wiki
          - design
          - null
        in: query
      - name: before
        required: false
        description: Return events created before the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: after
        required: false
        description: Return events created after the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: sort
        required: false
        description: Sort results in ascending or descending order by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
  /api/v4/users/{id}/events:
    get:
      operationId: getApiV4UsersIdEvents
      summary: Retrieve contribution events for a user
      description: Retrieves the contribution events for a specified user. Does not return events associated with epics or merge requests. Returns bulk push events with limited commit details.
      tags:
      - Events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesEvent'
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or username of the user.
        schema:
          type: string
        in: path
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      - name: action
        required: false
        description: Filter events by the specified [action type](https://docs.gitlab.com/user/profile/contributions_calendar/#user-contribution-events).
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_type
        required: false
        description: Filter events by target type.
        schema:
          type:
          - string
          - 'null'
          enum:
          - issue
          - milestone
          - merge_request
          - note
          - project
          - snippet
          - user
          - wiki
          - design
          - null
        in: query
      - name: before
        required: false
        description: Return events created before the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: after
        required: false
        description: Return events created after the specified date.
        schema:
          type:
          - string
          - 'null'
          format: date
        in: query
      - name: sort
        required: false
        description: Sort results in ascending or descending order by creation date.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        in: query
components:
  schemas:
    APIEntitiesPushEventPayload:
      type: object
      properties:
        commit_count:
          type: integer
          example: 1
        action:
          type: string
          example: pushed
        ref_type:
          type: string
          example: branch
        commit_from:
          type: string
          example: 50d4420237a9de7be1304607147aec22e4a14af7
        commit_to:
          type: string
          example: c5feabde2d8cd023215af4d2ceeb7a64839fc428
        ref:
          type: string
          example: master
        commit_title:
          type: string
          example: Add simple search to projects in public area
        ref_count:
          type: integer
          example: 1
    APIEntitiesEvent:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        project_id:
          type: integer
          format: int64
          example: 2
        action_name:
          type: string
          example: closed
        target_id:
          type: integer
          format: int64
          example: 160
        target_iid:
          type: integer
          example: 157
        target_type:
          type: string
          example: Issue
        author_id:
          type: integer
          format: int64
          example: 25
        target_title:
          type: string
          example: Public project search field
        created_at:
          type: string
          example: '2017-02-09T10:43:19.667Z'
        note:
          $ref: '#/components/schemas/APIEntitiesNote'
        author:
          $ref: '#/components/schemas/APIEntitiesUserBasic'
        wiki_page:
          $ref: '#/components/schemas/APIEntitiesWikiPageBasic'
        imported:
          type: boolean
          example: false
        imported_from:
          type: string
          example: none
        push_data:
          $ref: '#/components/schemas/APIEntitiesPushEventPayload'
        author_username:
          type: string
          example: root
    APIEntitiesNote:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        type:
          type: string
          example: DiscussionNote
        body:
          type: string
          example: Note body.
        author:
          $ref: '#/components/schemas/APIEntitiesUserBasic'
        created_at:
          type: string
          format: date-time
          example: '2022-01-31T15:10:44.988Z'
        updated_at:
          type: string
          format: date-time
          example: '2022-01-31T15:10:44.988Z'
        system:
          type: boolean
          example: false
        noteable_id:
          type: integer
          format: int64
          example: 1
        noteable_type:
          type: string
          example: Issue
        project_id:
          type: integer
          format: int64
          example: 1
        commit_id:
          type: string
          example: 7b09ce7e6f80347baf0316c8c94cdba9a0a7e91d
        position:
          type: object
        resolvable:
          type: boolean
          example: false
        resolved:
          type: boolean
          example: false
        resolved_by:
          $ref: '#/components/schemas/APIEntitiesUserBasic'
        resolved_at:
          type: string
          format: date-time
          example: '2022-01-31T15:10:44.988Z'
        suggestions:
          $ref: '#/components/schemas/APIEntitiesSuggestion'
        confidential:
          type: boolean
          example: false
        internal:
          type: boolean
          example: false
        imported:
          type: boolean
          example: false
        imported_from:
          type: string
          example: github
        noteable_iid:
          type: integer
          example: 1
        commands_changes:
          type: object
    APIEntitiesCustomAttribute:
      type: object
      properties:
        key:
          type: string
          example: foo
        value:
          type: string
          example: bar
    APIEntitiesSuggestion:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        from_line:
          type: integer
          example: 1
        to_line:
          type: integer
          example: 1
        appliable:
          type: boolean
          example: true
        applied:
          type: boolean
          example: false
        from_content:
          type: string
          example: 'Original content

            '
        to_content:
          type: string
          example: 'New content

            '
    APIEntitiesWikiPageBasic:
      type: object
      properties:
        format:
          type: string
          example: markdown
        slug:
          type: string
          example: deploy
        title:
          type: string
          example: deploy
        wiki_page_meta_id:
          type: integer
          format: int64
          example: 123
    APIEntitiesUserBasic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        username:
          type: string
          example: admin
        public_email:
          type: string
          example: john@example.com
        name:
          type: string
          example: Administrator
        state:
          type: string
          example: active
        locked:
          type: boolean
        avatar_url:
          type: string
          example: https://gravatar.com/avatar/1
        avatar_path:
          type: string
          example: /user/avatar/28/The-Big-Lebowski-400-400.png
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesCustomAttribute'
        web_url:
          type: string
          example: https://gitlab.example.com/root
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header