Azure DevOps Release Definitions API

openapi: 3.1.0
info:
  title: Azure DevOps Artifacts Attachments Release Definitions 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: Release Definitions
  description: Operations for managing release pipeline definitions
paths:
  /release/definitions:
    get:
      operationId: releaseDefinitions_list
      summary: Azure DevOps List release definitions
      description: 'Returns a list of release definitions in the project. Supports filtering by name and path. Definitions represent the release pipeline template including environments, artifacts, approval gates, and deployment steps.

        '
      tags:
      - Release Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: searchText
        in: query
        required: false
        description: Filter definitions by name (supports wildcards)
        schema:
          type: string
      - name: $expand
        in: query
        required: false
        description: Expand additional definition details
        schema:
          type: string
          enum:
          - environments
          - artifacts
          - none
          - lastRelease
          - tags
          - triggers
          - variables
      - name: artifactType
        in: query
        required: false
        description: Filter definitions by artifact type
        schema:
          type: string
          enum:
          - build
          - jenkins
          - github
          - nuget
          - team
          - externaltfsbuild
          - git
          - tfvc
      - name: artifactSourceId
        in: query
        required: false
        description: Filter definitions by artifact source ID
        schema:
          type: string
      - name: $top
        in: query
        required: false
        description: Maximum number of definitions to return
        schema:
          type: integer
      - name: continuationToken
        in: query
        required: false
        description: Continuation token for paged results
        schema:
          type: string
      - name: queryOrder
        in: query
        required: false
        description: Results ordering
        schema:
          type: string
          enum:
          - none
          - idAscending
          - idDescending
          - nameAscending
          - nameDescending
          - lastModifiedAscending
          - lastModifiedDescending
      - name: path
        in: query
        required: false
        description: Filter definitions by folder path
        schema:
          type: string
      responses:
        '200':
          description: List of release definitions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReleaseDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: releaseDefinitions_create
      summary: Azure DevOps Create a release definition
      description: 'Creates a new release definition specifying environments, artifacts, triggers, variables, and deployment steps. The definition serves as the template for future release instances.

        '
      tags:
      - Release Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        description: Release definition to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseDefinition'
      responses:
        '200':
          description: Release definition created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /release/definitions/{definitionId}:
    get:
      operationId: releaseDefinitions_get
      summary: Azure DevOps Get a release definition
      description: 'Returns detailed information about a specific release definition, including all environments, artifact sources, triggers, approvals, and deployment steps.

        '
      tags:
      - Release Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the release definition
        schema:
          type: integer
      - name: $expand
        in: query
        required: false
        description: Expand additional definition details
        schema:
          type: string
      - name: propertyFilters
        in: query
        required: false
        description: Comma-separated list of properties to include
        schema:
          type: string
      responses:
        '200':
          description: Release definition returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: releaseDefinitions_update
      summary: Azure DevOps Update a release definition
      description: 'Replaces an existing release definition with the provided definition. The revision number in the body must match the current revision to prevent concurrent modification conflicts.

        '
      tags:
      - Release Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the release definition to update
        schema:
          type: integer
      requestBody:
        required: true
        description: Updated release definition
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseDefinition'
      responses:
        '200':
          description: Release definition updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: releaseDefinitions_delete
      summary: Azure DevOps Delete a release definition
      description: 'Deletes a release definition. All associated releases must be deleted or abandoned first. This operation cannot be undone.

        '
      tags:
      - Release Definitions
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: definitionId
        in: path
        required: true
        description: Numeric ID of the release definition to delete
        schema:
          type: integer
      - name: comment
        in: query
        required: false
        description: Comment explaining why the definition is being deleted
        schema:
          type: string
      - name: forceDelete
        in: query
        required: false
        description: Force delete even if there are associated releases
        schema:
          type: boolean
      responses:
        '204':
          description: Release definition deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ConfigurationVariableValue:
      type: object
      description: A variable value in a release definition or release
      properties:
        value:
          type: string
          description: The variable value
        isSecret:
          type: boolean
          description: Whether the value is treated as a secret
        allowOverride:
          type: boolean
          description: Whether the value can be overridden when creating a release
    Artifact:
      type: object
      description: An artifact used in a release
      properties:
        alias:
          type: string
          description: Alias for the artifact within the release definition
          example: _MyBuild
        type:
          type: string
          description: Artifact type
          enum:
          - build
          - jenkins
          - github
          - nuget
          - team
          - externaltfsbuild
          - git
          - tfvc
        definitionReference:
          type: object
          description: Reference to the artifact source definition
          additionalProperties:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
        isPrimary:
          type: boolean
          description: Whether this is the primary artifact
        isRetained:
          type: boolean
          description: Whether this artifact is retained
        sourceId:
          type: string
          description: Source identifier for the artifact
    ReleaseDefinition:
      type: object
      description: A release pipeline definition
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the definition
        name:
          type: string
          description: Display name of the release definition
          example: Production Deployment
        path:
          type: string
          description: Folder path for the definition
          example: \Production
        description:
          type: string
          description: Description of the release definition
        revision:
          type: integer
          description: Current revision number
        createdOn:
          type: string
          format: date-time
        modifiedOn:
          type: string
          format: date-time
        createdBy:
          $ref: '#/components/schemas/IdentityRef'
        modifiedBy:
          $ref: '#/components/schemas/IdentityRef'
        isDeleted:
          type: boolean
          description: Whether this definition has been deleted
        environments:
          type: array
          description: Environments (deployment stages) in the release pipeline
          items:
            $ref: '#/components/schemas/ReleaseDefinitionEnvironment'
        artifacts:
          type: array
          description: Artifact sources used by this release definition
          items:
            $ref: '#/components/schemas/Artifact'
        triggers:
          type: array
          description: Triggers that automatically create releases
          items:
            type: object
        variables:
          type: object
          description: Release-level variables
          additionalProperties:
            $ref: '#/components/schemas/ConfigurationVariableValue'
        tags:
          type: array
          items:
            type: string
        source:
          type: string
          enum:
          - undefined
          - restApi
          - userInterface
          - ibiza
          - portalExtensionApi
        url:
          type: string
          format: uri
        _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
    ReleaseDefinitionEnvironment:
      type: object
      description: An environment definition within a release pipeline
      properties:
        id:
          type: integer
        name:
          type: string
          description: Name of the environment
          example: Production
        rank:
          type: integer
          description: Sequence order of the environment in the pipeline
        deployPhases:
          type: array
          description: Deployment phases in this environment
          items:
            type: object
        conditions:
          type: array
          description: Conditions that must be met before deploying to this environment
          items:
            type: object
        preDeployApprovals:
          type: object
          description: Pre-deployment approval configuration
        postDeployApprovals:
          type: object
          description: Post-deployment approval configuration
        environmentOptions:
          type: object
          description: Environment-level options
        variables:
          type: object
          description: Environment-level variables
          additionalProperties:
            $ref: '#/components/schemas/ConfigurationVariableValue'
        demands:
          type: array
          items:
            type: object
    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
  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'
  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.