> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Route a new user to the best dedicated iMessage line

> Returns the single best dedicated iMessage line to assign a new user to, load-balancing by active user count and recent growth. `isBestAvailable` is `false` when the returned line is the least-bad fallback — it holds more than 500 users or grew by more than 100 users in the last 10 minutes, meaning no genuinely healthy line was available. Returns 404 if the project owns no dedicated iMessage lines. Requires Authorization: Basic base64(projectId:projectSecret).



## OpenAPI

````yaml https://spectrum.photon.codes/openapi/json get /projects/{projectId}/lines/route
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/lines/route:
    get:
      tags:
        - lines
      summary: Route a new user to the best dedicated iMessage line
      description: >-
        Returns the single best dedicated iMessage line to assign a new user to,
        load-balancing by active user count and recent growth. `isBestAvailable`
        is `false` when the returned line is the least-bad fallback — it holds
        more than 500 users or grew by more than 100 users in the last 10
        minutes, meaning no genuinely healthy line was available. Returns 404 if
        the project owns no dedicated iMessage lines. Requires Authorization:
        Basic base64(projectId:projectSecret).
      operationId: getProjectsByProjectIdLinesRoute
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      line:
                        type: object
                        properties:
                          platform:
                            type: string
                            const: imessage
                          id:
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          phoneNumber:
                            type: string
                          status:
                            type: string
                            enum:
                              - available
                              - unavailable
                              - unknown
                          createdAt:
                            type: string
                        required:
                          - platform
                          - id
                          - phoneNumber
                          - status
                          - createdAt
                        additionalProperties: false
                      isBestAvailable:
                        type: boolean
                    required:
                      - line
                      - isBestAvailable
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false

````