openapi: 3.1.0
info:
  title: Lumen Internet On-Demand API
  description: >-
    The Lumen Internet On-Demand API enables programmatic provisioning and
    management of internet bandwidth services. It provides access to Lumen's
    global fiber network, allowing customers to dynamically adjust bandwidth,
    manage connections, and automate network provisioning through a secure
    REST API using OAuth 2.0 client credentials authentication.
  version: '2026-01-01'
  contact:
    name: Lumen Developer Center
    url: https://developer.lumen.com
  termsOfService: https://www.lumen.com/en-us/about/legal/api-developer-terms-and-conditions.html
externalDocs:
  description: Lumen Developer Center Documentation
  url: https://developer.lumen.com/apis/internet-on-demand
servers:
  - url: https://api.lumen.com
    description: Production
tags:
  - name: Bandwidth
    description: Bandwidth provisioning and adjustment
  - name: Connections
    description: Manage internet connections
security:
  - oauth2: []
paths:
  /internet-on-demand/connections:
    get:
      operationId: listConnections
      summary: List connections
      description: Retrieve a list of internet on-demand connections.
      tags:
        - Connections
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connection'
        '401':
          description: Unauthorized
    post:
      operationId: createConnection
      summary: Create a connection
      description: Provision a new internet on-demand connection.
      tags:
        - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionRequest'
      responses:
        '201':
          description: Connection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /internet-on-demand/connections/{connectionId}:
    get:
      operationId: getConnection
      summary: Get connection details
      description: Retrieve details of a specific connection.
      tags:
        - Connections
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found
  /internet-on-demand/connections/{connectionId}/bandwidth:
    put:
      operationId: updateBandwidth
      summary: Update bandwidth
      description: Dynamically adjust the bandwidth for an existing connection.
      tags:
        - Bandwidth
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BandwidthUpdate'
      responses:
        '200':
          description: Bandwidth updated
        '400':
          description: Bad request
        '404':
          description: Connection not found
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.lumen.com/oauth2/token
          scopes:
            read: Read access to connections
            write: Write access to connections
  schemas:
    Connection:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - active
            - provisioning
            - suspended
            - terminated
        bandwidth:
          type: string
        location:
          type: string
        createdAt:
          type: string
          format: date-time
    ConnectionRequest:
      type: object
      required:
        - bandwidth
        - locationId
      properties:
        bandwidth:
          type: string
        locationId:
          type: string
        description:
          type: string
    BandwidthUpdate:
      type: object
      required:
        - bandwidth
      properties:
        bandwidth:
          type: string
        effectiveDate:
          type: string
          format: date-time