openapi: 3.0.3
info:
  title: Published Updates API
  description: API for retrieving published customer updates
  version: 1.0.0
servers:
  - url: https://app.changebot.ai/api/v1
    description: Production server
paths:
  /updates:
    get:
      summary: Get published customer updates
      description: Retrieves a list of published customer updates for a specific team identified by slug
      operationId: getPublishedUpdates
      parameters:
        - name: slug
          in: query
          description: Unique slug identifier for the team
          required: true
          schema:
            type: string
            example: example-team
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
            example: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
            example: 20
      responses:
        "200":
          description: Successful operation
          headers:
            Link:
              description: HATEOAS navigation links in header
              schema:
                type: string
                example: <https://app.changebot.ai/api/v1/updates?slug=example-team&page=2&limit=20>; rel="next", <https://app.changebot.ai/api/v1/updates?slug=example-team&page=1&limit=20>; rel="prev"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdatesResponse"
        "404":
          description: Team slug not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Too many requests - rate limit exceeded (4 requests per minute)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    UpdatesResponse:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CustomerUpdate"
        links:
          type: object
          required:
            - self
            - first
            - last
          properties:
            self:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates?page=1&limit=20
            first:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates?page=1&limit=20
            last:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates?page=3&limit=20
            next:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates?page=2&limit=20
            prev:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates?page=1&limit=20
        meta:
          type: object
          required:
            - current_page
            - total_pages
            - total_count
            - limit
          properties:
            current_page:
              type: integer
              example: 1
            total_pages:
              type: integer
              example: 3
            total_count:
              type: integer
              example: 50
            limit:
              type: integer
              example: 20
    CustomerUpdate:
      type: object
      required:
        - id
        - type
        - attributes
        - links
      properties:
        id:
          type: integer
          example: 123
        type:
          type: string
          enum: [customer_update]
          example: customer_update
        attributes:
          type: object
          required:
            - title
            - content
            - published_at
          properties:
            title:
              type: string
              example: New Feature Announcement
            content:
              type: string
              example: We're excited to announce our latest feature...
            published_at:
              type: string
              format: date-time
              example: 2025-02-25T12:00:00Z
        links:
          type: object
          required:
            - self
          properties:
            self:
              type: string
              format: uri
              example: https://app.changebot.ai/api/v1/updates/123
    Error:
      type: object
      description: Empty response body for error conditions
      properties: {}
