GitLab

GitLab Broadcast Messages API

The Broadcast Messages API from GitLab — 2 operation(s) for broadcast messages.

GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v4/broadcast_messages List all broadcast messages · List all broadcast messages #
Ask an LLM
“What announcement banners are configured on the instance?”
“Where can I see every past and scheduled broadcast message?”
Tell an agent
List all broadcast messages.
Show page {page} of the broadcast messages.
POST /api/v4/broadcast_messages Create a broadcast message · Create a broadcast message #
Ask an LLM
“How do I post a maintenance banner to all users of my GitLab instance?”
“Can I schedule a broadcast to start and end at set times?”
Tell an agent
Create a broadcast message saying {message}.
Broadcast {message} from {starts_at} until {ends_at}.
GET /api/v4/broadcast_messages/{id} Get a broadcast message · Retrieve a broadcast message #
Ask an LLM
“How do I view one broadcast banner and its schedule?”
“What audience and dates are set on a specific broadcast message?”
Tell an agent
Show broadcast message {id}.
Get the text and schedule of broadcast {id}.
PUT /api/v4/broadcast_messages/{id} Update a broadcast message · Update a broadcast message #
Ask an LLM
“How do I change the wording or end date of an existing announcement banner?”
“Can I retarget an existing broadcast to certain access levels or paths?”
Tell an agent
Change the text of broadcast message {id} to {message}.
Extend broadcast {id} so it ends at {ends_at}.
DELETE /api/v4/broadcast_messages/{id} Delete a broadcast message · Delete a broadcast message #
Ask an LLM
“How do I take down an announcement banner from my GitLab instance?”
“Can I permanently delete a broadcast message?”
Tell an agent destructive · confirm first
Delete broadcast message {id}.
Remove the announcement banner {id}.

Documentation

📖
Documentation
https://docs.gitlab.com/api/groups/
📖
Authentication
https://docs.gitlab.com/api/rest/authentication/
📖
Documentation
https://docs.gitlab.com/api/projects/
📖
Documentation
https://docs.gitlab.com/api/applications/
📖
Documentation
https://docs.gitlab.com/api/avatar/
📖
Documentation
https://docs.gitlab.com/api/broadcast_messages/
📖
Documentation
https://docs.gitlab.com/api/bulk_imports/
📖
Documentation
https://docs.gitlab.com/api/settings/
📖
Documentation
https://docs.gitlab.com/api/metadata/
📖
Documentation
https://docs.gitlab.com/api/version/
📖
Documentation
https://docs.gitlab.com/api/rest/
📖
APIReference
https://docs.gitlab.com/api/api_resources/
📖
RateLimits
https://docs.gitlab.com/security/rate_limits/
📖
Documentation
https://docs.gitlab.com/api/oauth2/
📖
Authentication
https://docs.gitlab.com/integration/oauth_provider/
📖
Documentation
https://docs.gitlab.com/user/project/integrations/webhooks.html
📖
APIReference
https://docs.gitlab.com/api/project_webhooks/

Specifications

⚙
OpenAPI
https://artifacts.apis.io/gitlab/openapi/gitlab-broadcast-messages-api-openapi.yml
⚙
AsyncAPI
https://artifacts.apis.io/gitlab/asyncapi/gitlab-webhooks-asyncapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/gitlab/json-schema/gitlab-api-entities-broadcast-message-schema.json

Other Resources

🔗
SDKs
https://docs.gitlab.com/api/rest/third_party_clients/
🔗
Interactive Documentation
https://docs.gitlab.com/api/openapi/openapi_interactive/

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/gitlab:gitlab-broadcast-messages-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

gitlab-broadcast-messages-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: GitLab REST Broadcast messages 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: Broadcast messages
  description: 'Use this API to interact with banners and notifications displayed in the UI. For more information, see broadcast messages.


    GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:


    - Unauthenticated users result in `401 Unauthorized`.

    - Authenticated non-administrators result in `403 Forbidden`.'
  x-displayName: Broadcast messages
  externalDocs:
    url: https://docs.gitlab.com/api/broadcast_messages/
paths:
  /api/v4/broadcast_messages:
    get:
      operationId: getApiV4BroadcastMessages
      summary: List all broadcast messages
      description: Lists all broadcast messages for the instance.
      tags:
      - Broadcast messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSystemBroadcastMessage'
        '400':
          description: Bad Request
      parameters:
      - 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
    post:
      operationId: postApiV4BroadcastMessages
      summary: Create a broadcast message
      description: Creates a broadcast message.
      tags:
      - Broadcast messages
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSystemBroadcastMessage'
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4BroadcastMessagesRequest'
  /api/v4/broadcast_messages/{id}:
    get:
      operationId: getApiV4BroadcastMessagesId
      summary: Retrieve a broadcast message
      description: Retrieves a specified broadcast message.
      tags:
      - Broadcast messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSystemBroadcastMessage'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the broadcast message.
        schema:
          type: integer
        in: path
    put:
      operationId: putApiV4BroadcastMessagesId
      summary: Update a broadcast message
      description: Updates a specified broadcast message.
      tags:
      - Broadcast messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSystemBroadcastMessage'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the broadcast message.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4BroadcastMessagesIdRequest'
    delete:
      operationId: deleteApiV4BroadcastMessagesId
      summary: Delete a broadcast message
      description: Deletes a specified broadcast message.
      tags:
      - Broadcast messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSystemBroadcastMessage'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the broadcast message.
        schema:
          type: integer
        in: path
components:
  schemas:
    putApiV4BroadcastMessagesIdRequest:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          description: Message to display.
        starts_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Starting time, in UTC. When creating a message, defaults to the current time.
        ends_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Ending time, in UTC. When creating a message, defaults to one hour after the current time.
        color:
          type:
          - string
          - 'null'
          description: Background color hex code. Deprecated. Use `theme` instead.
        font:
          type:
          - string
          - 'null'
          description: Foreground color hex code. Deprecated. Use `theme` instead.
        target_access_levels:
          type:
          - array
          - 'null'
          items:
            type: integer
            enum:
            - 10
            - 15
            - 20
            - 30
            - 40
            - 50
          description: Target access levels (roles) of the broadcast message.
        target_path:
          type:
          - string
          - 'null'
          description: Target path of the broadcast message.
        broadcast_type:
          type:
          - string
          - 'null'
          enum:
          - banner
          - notification
          - null
          description: Appearance type of the broadcast message.
        dismissable:
          type:
          - boolean
          - 'null'
          description: If `true`, the user can dismiss the message.
        theme:
          type:
          - string
          - 'null'
          enum:
          - indigo
          - light-indigo
          - blue
          - light-blue
          - green
          - light-green
          - red
          - light-red
          - dark
          - light
          - null
          description: Color theme for the broadcast message. Applies only to banners.
    postApiV4BroadcastMessagesRequest:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          description: Message to display.
        starts_at:
          type: string
          format: date-time
          description: Starting time, in UTC. When creating a message, defaults to the current time.
        ends_at:
          type: string
          format: date-time
          description: Ending time, in UTC. When creating a message, defaults to one hour after the current time.
        color:
          type:
          - string
          - 'null'
          description: Background color hex code. Deprecated. Use `theme` instead.
        font:
          type:
          - string
          - 'null'
          description: Foreground color hex code. Deprecated. Use `theme` instead.
        target_access_levels:
          type:
          - array
          - 'null'
          items:
            type: integer
            enum:
            - 10
            - 15
            - 20
            - 30
            - 40
            - 50
          description: Target access levels (roles) of the broadcast message.
        target_path:
          type:
          - string
          - 'null'
          description: Target path of the broadcast message.
        broadcast_type:
          type: string
          enum:
          - banner
          - notification
          description: Appearance type of the broadcast message.
          default: banner
        dismissable:
          type:
          - boolean
          - 'null'
          description: If `true`, the user can dismiss the message.
        theme:
          type:
          - string
          - 'null'
          enum:
          - indigo
          - light-indigo
          - blue
          - light-blue
          - green
          - light-green
          - red
          - light-red
          - dark
          - light
          - null
          description: Color theme for the broadcast message. Applies only to banners.
      required:
      - message
    APIEntitiesSystemBroadcastMessage:
      type: object
      properties:
        id:
          type: integer
          format: int64
        message:
          type: string
          example: Example broadcast message
        starts_at:
          type: string
          format: date-time
          example: '2016-01-04T15:39:55.570Z'
        ends_at:
          type: string
          format: date-time
          example: '2016-01-06T15:39:55.570Z'
        color:
          type: string
          example: '#E75E40'
        font:
          type: string
          example: '#FFFFFF'
        target_access_levels:
          type: array
          example:
          - 10
          - 30
        target_path:
          type: string
          example: '*/welcome'
        broadcast_type:
          type: string
          example: banner
        theme:
          type: string
          example: indigo
        dismissable:
          type: boolean
        active:
          type: boolean
  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