openapi: 3.2.0
info:
  title: Starlink Public Managed Accounts 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: Managed Accounts
paths:
  /public/v2/managed/accounts/tree:
    get:
      tags:
      - Managed Accounts
      summary: 'Pre-Release: Get managed account tree'
      description: "Required permission: Managed Account Information, View.<br/>Gets the entire managed account hierarchy beneath the calling account.\n            \nThis endpoint is available for select audiences only."
      parameters:
      - name: ancestorAccountNumber
        in: query
        description: "The root account number to build the tree from. If not provided, uses the token's account.\n             This account number must be in the hierarchy underneath the calling account."
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
        '403':
          description: Missing required permission for this endpoint or resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '200':
          description: Account tree retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAccountTreeResponseV2ServiceResponse'
        '422':
          description: Failed to retrieve managed account tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
  /public/v2/managed/accounts:
    get:
      tags:
      - Managed Accounts
      summary: 'Pre-Release: Query managed accounts'
      description: "Required permission: Managed Account Information, View.<br/>Query managed accounts within your account hierarchy with filtering and pagination support.\nReturns up to 100 accounts at at time.\n            \nThis endpoint is available for select audiences only."
      parameters:
      - name: ancestorAccountNumber
        in: query
        description: "Query accounts under this ancestor account number.\n             Defaults to calling token's account if not provided."
        schema:
          type: string
      - name: searchString
        in: query
        description: Filter by account name or number (prefix match)
        schema:
          type: string
      - name: accountNumbers
        in: query
        description: Get specific accounts by account numbers
        schema:
          type: array
          items:
            type: string
      - name: maxDepth
        in: query
        description: "Maximum depth in hierarchy (1 = direct children only, 2 = children +\n             grandchildren, 3 = children through great-grandchildren, etc. null for all\n             descendants.)"
        schema:
          type: integer
          format: int32
      - name: cursor
        in: query
        description: Pagination cursor for fetching next page
        schema:
          type: string
      responses:
        '200':
          description: Managed accounts retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountQueryResponseV2KeyPaginatedStringServiceResponse'
        '401':
          description: Unauthorized
        '403':
          description: "Missing\n             required permission for this endpoint or resource"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '422':
          description: "Failed to\n             query managed accounts"
          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
    AccountQueryResponseV2KeyPaginatedStringServiceResponse:
      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/AccountQueryResponseV2KeyPaginatedString'
      additionalProperties: false
    ManagedAccountTreeNodeResponseV2:
      type: object
      properties:
        accountNumber:
          type: string
          description: The account number
        accountName:
          type: string
          description: The account name
        managerAccountNumber:
          type:
          - string
          - 'null'
          description: The manager account number (null for root)
        children:
          type: array
          items:
            type: string
          description: List of child account numbers
      additionalProperties: false
    ManagedAccountTreeResponseV2:
      type: object
      properties:
        rootAccountNumber:
          type: string
          description: The root account number
        tree:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ManagedAccountTreeNodeResponseV2'
          description: Dictionary mapping account numbers to tree nodes
      additionalProperties: false
    AccountQueryResponseV2KeyPaginatedString:
      type: object
      properties:
        nextKey:
          type:
          - string
          - 'null'
          description: The next key that should be provided to the cursor parameter to fetch the next page, or null if this is the last page.
        results:
          type: array
          items:
            $ref: '#/components/schemas/AccountQueryResponseV2'
          description: Results for this page.
      additionalProperties: false
    ValidationResult:
      type: object
      properties:
        memberNames:
          type:
          - array
          - 'null'
          items:
            type: string
          readOnly: true
        errorMessage:
          type:
          - string
          - 'null'
      additionalProperties: false
    AccountQueryResponseV2:
      type: object
      properties:
        accountNumber:
          type: string
          description: 'The Account Number. Example: ACC-511274-31364-54'
        regionCode:
          type: string
          description: 'The region code of the account. Example: US'
        accountName:
          type: string
          description: The name of the account
      additionalProperties: false
    ManagedAccountTreeResponseV2ServiceResponse:
      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/ManagedAccountTreeResponseV2'
      additionalProperties: false