openapi: 3.0.3
info:
  title: Microsoft 365 Roadmap API
  description: |
    The Microsoft 365 Roadmap API provides access to roadmap items for Microsoft 365 products and services.
    This API uses the OData protocol for querying and filtering data.
  version: 2.0.0
  contact:
    name: Microsoft Release Communications
    url: https://www.microsoft.com/releasecommunications
servers:
  - url: https://www.microsoft.com/releasecommunications/api/v2
    description: Production server
paths:
  /m365:
    get:
      summary: Get Microsoft 365 roadmap items
      description: |
        Retrieve roadmap items with optional filtering, sorting, and pagination.
        Supports OData query parameters for advanced filtering and data manipulation.
      operationId: getM365RoadmapItems
      parameters:
        - name: $filter
          in: query
          description: |
            Filter the results using OData filter syntax.
            Examples:
            - `products/any(p: contains(tolower(p), 'teams'))` - Filter by product containing 'teams'
            - `status eq 'In development'` - Filter by status
            - `created ge 2023-01-01T00:00:00Z` - Filter by creation date
          required: false
          schema:
            type: string
          examples:
            products_filter:
              summary: Filter by product
              description: Find items for a specific product
              value: "products/any(p: contains(tolower(p), 'excel'))"
            status_filter:
              summary: Filter by status
              description: Find items with specific status
              value: "status eq 'In development'"
            date_filter:
              summary: Filter by date
              description: Find items created after a specific date
              value: "created ge 2023-01-01T00:00:00Z"
        - name: $select
          in: query
          description: |
            Select specific fields to return.
            Example: `id,title,status,products`
          required: false
          schema:
            type: string
          example: "id,title,status,products"
        - name: $orderby
          in: query
          description: |
            Sort the results by one or more fields.
            Examples:
            - `created desc` - Sort by creation date descending
            - `title asc` - Sort by title ascending
            - `modified desc, created asc` - Multiple sort fields
          required: false
          schema:
            type: string
          examples:
            created_desc:
              summary: Sort by creation date
              description: Sort items by creation date in descending order
              value: "created desc"
            title_asc:
              summary: Sort by title
              description: Sort items by title in ascending order
              value: "title asc"
        - name: $top
          in: query
          description: Limit the number of results returned
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 1000
          example: 50
        - name: $skip
          in: query
          description: Skip a number of results (for pagination)
          required: false
          schema:
            type: integer
            minimum: 0
          example: 100
        - name: $count
          in: query
          description: Include the total count of items in the response
          required: false
          schema:
            type: boolean
          example: true
        - name: $expand
          in: query
          description: Expand related entities
          required: false
          schema:
            type: string
          example: "availabilities"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/M365RoadmapResponse'
              examples:
                single_item:
                  summary: Single roadmap item
                  description: Example response with one roadmap item
                  value:
                    "@odata.context": "https://relcomms-prod-dagnegedescbeefs.b02.azurefd.net/api/v2/$metadata#M365"
                    "value": [
                      {
                        "id": 65632,
                        "title": "Excel: Refresh queries from Authenticated Data Sources in Excel for the Web",
                        "description": "<div>You can now refresh Power Query data from data sources that require authentication in Excel for the Web.</div>",
                        "cloudInstances": ["Worldwide (Standard Multi-Tenant)", "GCC", "GCC High", "DoD"],
                        "platforms": ["Web"],
                        "releaseRings": ["General Availability", "Targeted Release (Entire Organization)"],
                        "moreInfoUrls": [],
                        "products": ["Excel"],
                        "generalAvailabilityDate": "2025-05",
                        "previewAvailabilityDate": null,
                        "created": "2023-08-22T23:16:17.6100000Z",
                        "status": "In development",
                        "modified": "2025-04-29T23:15:05.1130514Z",
                        "locale": null,
                        "availabilities": [
                          {
                            "ring": "General Availability",
                            "year": 2025,
                            "month": "May"
                          }
                        ]
                      }
                    ]
        '400':
          description: Bad Request - Invalid OData query syntax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /$metadata:
    get:
      summary: Get OData metadata
      description: Retrieve the OData metadata document that describes the data model
      operationId: getMetadata
      responses:
        '200':
          description: OData metadata document
          content:
            application/xml:
              schema:
                type: string
components:
  schemas:
    M365RoadmapResponse:
      type: object
      properties:
        "@odata.context":
          type: string
          description: OData context URL
          example: "https://relcomms-prod-dagnegedescbeefs.b02.azurefd.net/api/v2/$metadata#M365"
        "@odata.count":
          type: integer
          description: Total count of items (when $count=true is specified)
          example: 1250
        value:
          type: array
          items:
            $ref: '#/components/schemas/RoadmapItem'
      required:
        - "@odata.context"
        - value
    RoadmapItem:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the roadmap item
          example: 65632
        title:
          type: string
          description: Title of the roadmap item
          example: "Excel: Refresh queries from Authenticated Data Sources in Excel for the Web"
        description:
          type: string
          description: Detailed description of the feature (may contain HTML)
          example: "<div>You can now refresh Power Query data from data sources that require authentication in Excel for the Web.</div>"
        cloudInstances:
          type: array
          items:
            type: string
            enum:
              - "Worldwide (Standard Multi-Tenant)"
              - "GCC"
              - "GCC High" 
              - "DoD"
              - "China"
          description: Cloud instances where the feature will be available
        platforms:
          type: array
          items:
            type: string
            enum:
              - "Web"
              - "Desktop"
              - "Mobile"
              - "Mac"
          description: Platforms where the feature will be available
        releaseRings:
          type: array
          items:
            type: string
            enum:
              - "General Availability"
              - "Targeted Release (Entire Organization)"
              - "Targeted Release (Select Users)"
          description: Release rings for feature rollout
        moreInfoUrls:
          type: array
          items:
            type: string
            format: uri
          description: Additional information URLs
        products:
          type: array
          items:
            type: string
          description: Microsoft 365 products associated with this roadmap item
          example: ["Excel"]
        generalAvailabilityDate:
          type: string
          nullable: true
          description: Expected general availability date (YYYY-MM format)
          example: "2025-05"
        previewAvailabilityDate:
          type: string
          nullable: true
          description: Preview availability date (YYYY-MM format)
          example: "2025-03"
        created:
          type: string
          format: date-time
          description: Date and time when the roadmap item was created
          example: "2023-08-22T23:16:17.6100000Z"
        status:
          type: string
          enum:
            - "In development"
            - "Rolling out"
            - "Launched"
            - "Cancelled"
          description: Current status of the roadmap item
          example: "In development"
        modified:
          type: string
          format: date-time
          description: Date and time when the roadmap item was last modified
          example: "2025-04-29T23:15:05.1130514Z"
        locale:
          type: string
          nullable: true
          description: Locale information
          example: null
        availabilities:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
          description: Availability timeline information
      required:
        - id
        - title
        - description
        - status
        - created
        - modified
    Availability:
      type: object
      properties:
        ring:
          type: string
          enum:
            - "General Availability"
            - "Targeted Release (Entire Organization)"
            - "Targeted Release (Select Users)"
          description: Release ring
          example: "General Availability"
        year:
          type: integer
          description: Release year
          example: 2025
        month:
          type: string
          description: Release month name
          example: "May"
      required:
        - ring
        - year
        - month
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Error message
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
          required:
            - code
            - message
      required:
        - error
tags:
  - name: M365 Roadmap
    description: Microsoft 365 roadmap items and featuresopenapi: 3.0.3
info:
  title: Microsoft 365 Roadmap API
  description: |
    The Microsoft 365 Roadmap API provides access to Microsoft 365 feature roadmap information.
    This API uses OData protocol for querying and filtering data.
  version: 2.0.0
  contact:
    name: Microsoft Release Communications
    url: https://www.microsoft.com/releasecommunications/
  license:
    name: Microsoft Terms of Use
    url: https://www.microsoft.com/legal/terms-of-use

servers:
  - url: https://www.microsoft.com/releasecommunications/api/v2
    description: Production server

paths:
  /m365:
    get:
      summary: Get Microsoft 365 roadmap items
      description: |
        Retrieve roadmap items with optional filtering, sorting, and pagination.
        Supports OData query parameters for advanced filtering and data manipulation.
        Always use 'created' field for date operations, not 'createdDateTime'.
      operationId: getM365RoadmapInfo
      parameters:
        - name: $filter
          in: query
          description: |
            OData filter expression to limit results. 
            Examples:
            - Filter by product: products/any(p: contains(tolower(p), 'teams'))
            - Filter by date: created gt 2023-01-01T00:00:00Z
            - Filter by title: contains(tolower(title), 'copilot')
            - Complex filter: contains(tolower(description), 'agent') and (products/any(p: contains(tolower(p), 'purview')) or products/any(p: contains(tolower(p), 'copilot')))
          required: false
          schema:
            type: string
          examples:
            teams_products:
              summary: Teams products
              description: Find roadmap items for Microsoft Teams
              value: "products/any(p: contains(tolower(p), 'teams'))"
            recent_items:
              summary: Recent items
              description: Find items created in the last 30 days
              value: "created gt 2023-12-01T00:00:00Z"
            title_search:
              summary: Title search
              description: Find items with 'copilot' in the title
              value: "contains(tolower(title), 'copilot')"
            complex_filter:
              summary: Complex filter
              description: Find agent-related items for Purview or Copilot
              value: "contains(tolower(description), 'agent') and (products/any(p: contains(tolower(p), 'purview')) or products/any(p: contains(tolower(p), 'copilot')))"
        
        - name: $orderby
          in: query
          description: |
            OData orderby expression to sort results.
            Examples: 'created desc', 'title asc', 'modified desc'
          required: false
          schema:
            type: string
          examples:
            created_desc:
              summary: Newest first
              value: "created desc"
            title_asc:
              summary: Alphabetical by title
              value: "title asc"
            modified_desc:
              summary: Recently modified first
              value: "modified desc"
        
        - name: $top
          in: query
          description: |
            Number of items to return (pagination).
            Use with $skip for pagination. Set to 0 to get count only.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 1000
            default: 50
          examples:
            default_page:
              summary: Default page size
              value: 50
            count_only:
              summary: Count only (no items)
              value: 0
            large_page:
              summary: Large page
              value: 100
        
        - name: $skip
          in: query
          description: Number of items to skip (pagination offset)
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        
        - name: $count
          in: query
          description: Include total count of matching items in response
          required: false
          schema:
            type: boolean
            default: false
        
        - name: $select
          in: query
          description: |
            Comma-separated list of fields to include in response.
            Examples: 'id,title', 'id,title,description,products'
          required: false
          schema:
            type: string
          examples:
            basic_fields:
              summary: Basic information
              value: "id,title,description"
            full_details:
              summary: All fields
              value: "id,title,description,products,created,modified,availabilities"
        
        - name: $expand
          in: query
          description: OData expand expression to include related data
          required: false
          schema:
            type: string

      responses:
        '200':
          description: Successful response with roadmap items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoadmapResponse'
              examples:
                teams_features:
                  summary: Teams features example
                  value:
                    "@odata.context": "https://www.microsoft.com/releasecommunications/api/v2/$metadata#m365"
                    "@odata.count": 150
                    "value": [
                      {
                        "id": 12345,
                        "title": "New Feature in Microsoft Teams",
                        "description": "This feature allows users to collaborate more effectively with enhanced meeting capabilities and AI-powered insights.",
                        "products": ["Teams"],
                        "created": "2023-01-01T00:00:00Z",
                        "modified": "2023-01-15T10:30:00Z",
                        "availabilities": [
                          {
                            "channel": "General Availability",
                            "year": 2024,
                            "month": "March",
                            "quarter": "Q1"
                          }
                        ]
                      }
                    ]
                
                copilot_features:
                  summary: Copilot features example
                  value:
                    "@odata.context": "https://www.microsoft.com/releasecommunications/api/v2/$metadata#m365"
                    "@odata.count": 75
                    "value": [
                      {
                        "id": 67890,
                        "title": "Microsoft 365 Copilot Integration",
                        "description": "Enhanced AI capabilities across Microsoft 365 applications with natural language processing and automated task completion.",
                        "products": ["Microsoft 365", "Office"],
                        "created": "2023-06-15T14:20:00Z",
                        "modified": "2023-07-01T09:15:00Z",
                        "availabilities": [
                          {
                            "channel": "Preview",
                            "year": 2023,
                            "month": "September",
                            "quarter": "Q3"
                          }
                        ]
                      }
                    ]
        
        '400':
          description: Bad request - Invalid OData query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    RoadmapResponse:
      type: object
      properties:
        "@odata.context":
          type: string
          description: OData context URL
          example: "https://www.microsoft.com/releasecommunications/api/v2/$metadata#m365"
        "@odata.count":
          type: integer
          description: Total count of items (when $count=true)
          example: 150
        "@odata.nextLink":
          type: string
          description: URL for next page of results (when applicable)
        value:
          type: array
          items:
            $ref: '#/components/schemas/RoadmapItem'
          description: Array of roadmap items
    
    RoadmapItem:
      type: object
      required:
        - id
        - title
        - description
        - products
        - created
      properties:
        id:
          type: integer
          description: Unique identifier for the roadmap item
          example: 12345
        title:
          type: string
          description: Title of the feature or update
          example: "New Feature in Microsoft Teams"
        description:
          type: string
          description: Detailed description of the feature
          example: "This feature allows users to collaborate more effectively with enhanced meeting capabilities."
        products:
          type: array
          items:
            type: string
          description: List of Microsoft 365 products affected
          example: ["Teams", "Office"]
        created:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601 format)
          example: "2023-01-01T00:00:00Z"
        modified:
          type: string
          format: date-time
          description: Last modification timestamp (ISO 8601 format)
          example: "2023-01-15T10:30:00Z"
        availabilities:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
          description: Availability timeline information
        category:
          type: string
          description: Feature category
          example: "Collaboration"
        status:
          type: string
          description: Current status of the feature
          enum: ["In Development", "Preview", "General Availability", "Cancelled"]
          example: "In Development"
        tags:
          type: array
          items:
            type: string
          description: Associated tags for categorization
          example: ["AI", "Productivity", "Collaboration"]
    
    Availability:
      type: object
      properties:
        channel:
          type: string
          description: Release channel
          enum: ["Preview", "General Availability", "Targeted Release"]
          example: "General Availability"
        year:
          type: integer
          description: Release year
          example: 2024
        month:
          type: string
          description: Release month
          example: "March"
        quarter:
          type: string
          description: Release quarter
          enum: ["Q1", "Q2", "Q3", "Q4"]
          example: "Q1"
        date:
          type: string
          format: date
          description: Specific release date (when available)
          example: "2024-03-15"
    
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: "InvalidRequest"
            message:
              type: string
              description: Human-readable error message
              example: "The request is invalid due to malformed OData query parameters."
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  target:
                    type: string
              description: Additional error details
        
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication (if required)

security:
  - ApiKeyAuth: []

tags:
  - name: Roadmap
    description: Microsoft 365 roadmap operations