openapi: 3.2.0
info:
  title: Starlink Public Data Pools API
  description: '<h3>Description</h3>API to manage Starlink accounts and devices. For interactive endpoints list see: <a href=''https://starlink.readme.io/''>https://starlink.readme.io/</a><h3>Authentication - OIDC</h3><p>To authenticate with this API using OIDC, <a target=''_blank'' href=''/api/auth/.well-known/openid-configuration''>Well Known URL</a> and attach the result to your requests with the <strong>Authorize</strong> button below.</p>'
  version: '2'
servers:
- url: /api
tags:
- name: Data Pools
paths:
  /public/v2/data-pools:
    get:
      tags:
      - Data Pools
      summary: 'Pre-Release: Get all multi-service line enabled data pools.'
      description: 'Required permission: Service plan, View.<br/>This endpoint is available for select audiences only.'
      parameters:
      - name: productReferenceId
        in: query
        description: Filter by Product ID of the pool
        schema:
          type: string
      - name: dataPoolIds
        in: query
        description: Data pool IDs to filter by. Queries for all data pools on account if omitted
        schema:
          type: array
          items:
            type: string
      - name: page
        in: query
        description: The index of the page, starting at 0. Page size is 100
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataPoolResponseV2PaginatedServiceResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
  /public/v2/data-pools/usage:
    get:
      tags:
      - Data Pools
      summary: 'Pre-Release: Query data pool usage with service line and monthly breakdowns.'
      description: 'Required permission: Service plan, View.<br/>This endpoint is available for select audiences only.'
      parameters:
      - name: dataPoolIds
        in: query
        description: Data pool Ids to filter by. Queries for usage of all data pools on account if omitted
        schema:
          type: array
          items:
            type: string
      - name: asOfTimestamp
        in: query
        description: "Optional timestamp for snapshotting data pool usage *as of* this time. Only includes data blocks\n            that are active at this instant (i.e., `StartDate <= asOfTimestamp < EndDate`).\n            Defaults to `DateTimeOffset.UtcNow` to return currently active blocks."
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        description: The index of the page, starting at 0.
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: Amount of data pool usage summaries to retrieve per page. Defaults to 50, can request up to 100.
        schema:
          type: integer
          format: int32
          default: 50
      responses:
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataPoolUsageResponseV2PaginatedServiceResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
  /public/v2/data-pools/{dataPoolId}/set-automatic-top-up:
    post:
      tags:
      - Data Pools
      summary: 'Pre-Release: Enable or disable automatic top-up for a data pool.'
      description: 'Required permission: Service plan, Edit.<br/>This endpoint is available for select audiences only.'
      parameters:
      - name: dataPoolId
        in: path
        description: The data pool ID
        required: true
        schema:
          type: string
      - name: enabled
        in: query
        description: Whether automatic top-up should be enabled (defaults to true)
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
components:
  schemas:
    ServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
      additionalProperties: false
    DataPoolResponseV2PaginatedServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
        content:
          $ref: '#/components/schemas/DataPoolResponseV2Paginated'
      additionalProperties: false
    DataBlockMonthlyResponseV2:
      type: object
      properties:
        startDate:
          type: string
          description: Start date of the respective month.
          format: date-time
        endDate:
          type: string
          description: End date of the respective month.
          format: date-time
        serviceLineUsage:
          type: array
          items:
            $ref: '#/components/schemas/DataBlockServiceLineUsagePublicResponseV2'
          description: Montly usage breakdown by service lines.
      additionalProperties: false
    DataBlockServiceLineUsagePublicResponseV2:
      type: object
      properties:
        serviceLineNumber:
          type: string
          description: Service line number.
        consumedAmountGB:
          type: number
          description: GB amount that the service line consumed from the block.
          format: double
      additionalProperties: false
    ValidationResult:
      type: object
      properties:
        memberNames:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        errorMessage:
          type:
          - string
          - 'null'
      additionalProperties: false
    DataPoolUsageResponseV2Paginated:
      type: object
      properties:
        pageIndex:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        isLastPage:
          type: boolean
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DataPoolUsageResponseV2'
        totalCount:
          type: integer
          format: int32
      additionalProperties: false
    DataPoolResponseV2:
      type: object
      properties:
        dataPoolId:
          type: string
          description: Data pool ID.
        nickname:
          type:
          - string
          - 'null'
          description: Nickname of the data pool.
        automaticTopUpEnabled:
          type: boolean
          description: If the data pool is opted-in to overage top-ups.
        restricted:
          type: boolean
          description: If the data pool and service lines on it are restricted due to exhausting their data
        dataProductType:
          $ref: '#/components/schemas/DataProductType'
        dataBlocks:
          type: array
          items:
            $ref: '#/components/schemas/DataBlockResponseV2'
          description: Active data blocks on the data pool.
        productId:
          type: string
          description: Product ID of the data pool.
      additionalProperties: false
    DataBlockUsageResponseV2:
      type: object
      properties:
        startDate:
          type: string
          description: UTC start date of the data block.
          format: date-time
        endDate:
          type: string
          description: UTC end date of the data block.
          format: date-time
        totalAmountGB:
          type: number
          description: Total GB capacity, calculated by multiplying BlocksCount and PerBlockAmountGB.
          format: double
        consumedAmountGB:
          type: number
          description: How much data has been used on the block.
          format: double
        perBlockAmountGB:
          type: number
          description: GB capacity per individual block.
          format: double
        dataBlockType:
          $ref: '#/components/schemas/DataBlockType'
        productId:
          type: string
          description: Product ID of the data block.
        blocksCount:
          type: integer
          description: Number of data blocks.
          format: int32
        serviceLineUsage:
          type: array
          items:
            $ref: '#/components/schemas/DataBlockServiceLineUsagePublicResponseV2'
          description: Usage breakdown by service lines.
        monthlyUsage:
          type: array
          items:
            $ref: '#/components/schemas/DataBlockMonthlyResponseV2'
          description: Usage breakdown by month.
      additionalProperties: false
    DataBlockType:
      enum:
      - IncludedWithBaseSubscription
      - RecurringPerBillingCycle
      - Overage
      - OneTimePurchase
      type: string
      x-enumNames:
      - IncludedWithBaseSubscription
      - RecurringPerBillingCycle
      - Overage
      - OneTimePurchase
    DataProductType:
      enum:
      - Ocean
      - Land
      - Aviation
      type: string
      x-enumNames:
      - Ocean
      - Land
      - Aviation
    DataPoolResponseV2Paginated:
      type: object
      properties:
        pageIndex:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        isLastPage:
          type: boolean
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DataPoolResponseV2'
        totalCount:
          type: integer
          format: int32
      additionalProperties: false
    DataPoolUsageResponseV2:
      type: object
      properties:
        dataPoolId:
          type: string
          description: Data pool ID.
        dataBlocks:
          type: array
          items:
            $ref: '#/components/schemas/DataBlockUsageResponseV2'
          description: Usage by data blocks in the pool.
      additionalProperties: false
    DataBlockResponseV2:
      type: object
      properties:
        productId:
          type: string
          description: Product ID of the data block.
        startDate:
          type: string
          description: Start date of the data block, i.e. when it is active for consumption.
          format: date-time
        endDate:
          type: string
          description: End date of the data block, i.e. when it is no longer active for consumption.
          format: date-time
        isPrepaid:
          type: boolean
          description: If the data block is prepaid.
        blocksCount:
          type: integer
          description: Number of data blocks.
          format: int32
        type:
          $ref: '#/components/schemas/DataBlockType'
        dataAmountGB:
          type: number
          description: GB capacity per individual block.
          format: double
      additionalProperties: false
    DataPoolUsageResponseV2PaginatedServiceResponse:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ValidationResult'
          readOnly: true
        information:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        isValid:
          type: boolean
          readOnly: true
        content:
          $ref: '#/components/schemas/DataPoolUsageResponseV2Paginated'
      additionalProperties: false