Azure DevOps Subscriptions API

openapi: 3.1.0
info:
  title: Azure DevOps Artifacts Attachments Subscriptions API
  description: 'REST API for managing packages, feeds, and artifact dependencies in Azure Artifacts. Supports NuGet, npm, Maven, Python, and Universal package formats in private or public feeds. Enables programmatic management of package feeds, discovery of packages and their versions, and lifecycle operations such as deprecating or deleting package versions.

    '
  version: '7.1'
  contact:
    name: Microsoft Azure DevOps
    url: https://learn.microsoft.com/en-us/rest/api/azure/devops/artifacts/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://feeds.dev.azure.com/{organization}/{project}/_apis
  description: Azure DevOps Artifacts API (project-scoped)
  variables:
    organization:
      description: Azure DevOps organization name or ID
      default: myorganization
    project:
      description: Azure DevOps project name or ID
      default: myproject
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Subscriptions
  description: Operations for managing service hook subscriptions
paths:
  /hooks/subscriptions:
    get:
      operationId: subscriptions_list
      summary: Azure DevOps List subscriptions
      description: 'Returns a list of all service hook subscriptions in the organization. Each subscription specifies an event type, publisher, consumer (webhook endpoint), and filter conditions. Supports optional filtering by publisher and consumer.

        '
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: publisherId
        in: query
        required: false
        description: Filter subscriptions by publisher ID (e.g., 'tfs')
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        description: Filter subscriptions by event type (e.g., 'workitem.created')
        schema:
          type: string
      - name: consumerId
        in: query
        required: false
        description: Filter subscriptions by consumer ID (e.g., 'webHooks')
        schema:
          type: string
      - name: consumerActionId
        in: query
        required: false
        description: Filter subscriptions by consumer action ID
        schema:
          type: string
      responses:
        '200':
          description: List of subscriptions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of subscriptions returned
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: subscriptions_create
      summary: Azure DevOps Create a subscription
      description: 'Creates a new service hook subscription. The subscription defines which event to listen for (publisher + eventType), filter conditions to narrow the event scope (e.g., a specific project or branch), and the consumer endpoint to deliver the notification to.

        '
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        description: Subscription configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreateRequest'
            example:
              publisherId: tfs
              eventType: workitem.created
              resourceVersion: '1.0'
              consumerId: webHooks
              consumerActionId: httpRequest
              publisherInputs:
                projectId: a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4
                workItemType: Bug
                areaPath: MyProject
              consumerInputs:
                url: https://myserver.example.com/webhook
                httpHeaders: 'X-Custom-Header: my-value'
                messagesToSend: none
                detailedMessagesToSend: all
                resourceDetailsToSend: all
      responses:
        '200':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /hooks/subscriptions/{subscriptionId}:
    get:
      operationId: subscriptions_get
      summary: Azure DevOps Get a subscription
      description: 'Returns detailed information about a specific service hook subscription, including its publisher, event type, consumer configuration, filter inputs, and current status.

        '
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: subscriptionId
        in: path
        required: true
        description: GUID of the subscription
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Subscription returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: subscriptions_update
      summary: Azure DevOps Update a subscription
      description: 'Updates properties of an existing service hook subscription such as the consumer endpoint URL, filter conditions, or resource detail settings.

        '
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: subscriptionId
        in: path
        required: true
        description: GUID of the subscription to update
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        description: Updated subscription properties
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreateRequest'
      responses:
        '200':
          description: Subscription updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: subscriptions_delete
      summary: Azure DevOps Delete a subscription
      description: 'Permanently deletes a service hook subscription. After deletion, the consumer endpoint will no longer receive notifications for the configured event type.

        '
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: subscriptionId
        in: path
        required: true
        description: GUID of the subscription to delete
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Subscription deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  parameters:
    ApiVersion:
      name: api-version
      in: query
      required: true
      description: Azure DevOps REST API version. Use 7.1 for the latest stable version.
      schema:
        type: string
        default: '7.1'
        enum:
        - '7.1'
        - '7.0'
        - '6.0'
  schemas:
    SubscriptionCreateRequest:
      type: object
      description: Request body for creating or updating a service hook subscription
      required:
      - publisherId
      - eventType
      - consumerId
      - consumerActionId
      - publisherInputs
      - consumerInputs
      properties:
        publisherId:
          type: string
          description: Publisher ID for the event source
          example: tfs
        eventType:
          type: string
          description: Event type to subscribe to
          example: workitem.created
        resourceVersion:
          type: string
          description: Version of the event resource schema to use
          example: '1.0'
          default: '1.0'
        consumerId:
          type: string
          description: Consumer ID for the notification target
          example: webHooks
        consumerActionId:
          type: string
          description: Action ID within the consumer
          example: httpRequest
        publisherInputs:
          type: object
          description: Filter inputs controlling which events trigger a notification
          additionalProperties:
            type: string
        consumerInputs:
          type: object
          description: Configuration for the consumer endpoint
          additionalProperties:
            type: string
    Subscription:
      type: object
      description: A service hook subscription that delivers event notifications to a consumer
      properties:
        id:
          type: string
          format: uuid
          description: Unique GUID identifier of the subscription
        status:
          type: string
          description: Current health status of the subscription
          enum:
          - enabled
          - onProbation
          - disabledByUser
          - disabledBySystem
          - disabledByInactiveIdentity
        publisherId:
          type: string
          description: Identifier of the publisher (event source)
          example: tfs
        eventType:
          type: string
          description: Type of event this subscription listens for
          example: workitem.created
        resourceVersion:
          type: string
          description: Version of the event resource schema
          example: '1.0'
        consumerId:
          type: string
          description: Identifier of the consumer (notification target)
          example: webHooks
        consumerActionId:
          type: string
          description: Identifier of the specific consumer action
          example: httpRequest
        publisherInputs:
          type: object
          description: Filter inputs for the event publisher (project ID, event conditions)
          additionalProperties:
            type: string
          example:
            projectId: a1b2c3d4-e5f6-a1b2-c3d4-e5f6a1b2c3d4
            workItemType: Bug
            areaPath: MyProject
        consumerInputs:
          type: object
          description: Configuration inputs for the consumer (URL, headers, auth)
          additionalProperties:
            type: string
          example:
            url: https://myserver.example.com/webhook
            resourceDetailsToSend: all
        modifiedBy:
          $ref: '#/components/schemas/IdentityRef'
        modifiedDate:
          type: string
          format: date-time
          description: Date and time the subscription was last modified
        createdBy:
          $ref: '#/components/schemas/IdentityRef'
        createdDate:
          type: string
          format: date-time
          description: Date and time the subscription was created
        url:
          type: string
          format: uri
          description: URL to access this subscription via the REST API
        _links:
          type: object
          additionalProperties:
            type: object
            properties:
              href:
                type: string
                format: uri
    IdentityRef:
      type: object
      description: Reference to an Azure DevOps user identity
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
          example: John Doe
        uniqueName:
          type: string
          example: john.doe@example.com
        url:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
        descriptor:
          type: string
    ApiError:
      type: object
      description: Error response from the Azure DevOps API
      properties:
        id:
          type: string
          format: uuid
        message:
          type: string
        typeName:
          type: string
        typeKey:
          type: string
        errorCode:
          type: integer
        eventId:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Azure AD OAuth 2.0 bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Personal Access Token (PAT). Use any string as the username and the PAT as the password, then base64-encode the result.