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

# search available numbers

> live carrier inventory (India). each number carries its monthly rent, setup fee and inbound / outbound per-minute rates, converted to the wallet's currency (`*Nanos` = billionths of a currency unit, so `236250000000` nanos INR is ₹236.25). filter by a digit `pattern` or a `city`.



## OpenAPI

````yaml /openapi.json get /v1/phone-numbers/available
openapi: 3.1.0
info:
  title: silk api
  version: 1.0.0
  description: >-
    rumik ai's speech api. synthesize speech with the expressive `muga` model,
    the faster `mulberry` model or the multilingual `mulberry-1.6` model over
    http or a streaming websocket session, run conversational voice agents over
    webrtc, a realtime pcm socket or the phone, and manage everything the agents
    playground does — agents, voices, variables, tools, phone numbers, sip
    trunks and outbound calls — with the same api key.
  contact:
    name: rumik ai
    url: https://rumik.ai
servers:
  - url: https://silk-api.rumik.ai
    description: production
security:
  - bearerAuth: []
tags:
  - name: speech
    description: text-to-speech over HTTP and WebSocket.
  - name: voice agents
    description: start calls with a deployed agent from your own app.
  - name: agents
    description: build, configure, deploy and inspect your agents.
  - name: calls
    description: place outbound phone calls and read call history.
  - name: voices
    description: the voices, languages and styles an agent may use.
  - name: variables
    description: account-wide `{name}` prompt variables and their defaults.
  - name: tools
    description: HTTP tools agents call before or during a call.
  - name: phone numbers
    description: 'numbers rented through rumik: search, rent, connect, release.'
  - name: sip trunks
    description: bring your own numbers over SIP.
paths:
  /v1/phone-numbers/available:
    get:
      tags:
        - phone numbers
      summary: search available numbers
      description: >-
        live carrier inventory (India). each number carries its monthly rent,
        setup fee and inbound / outbound per-minute rates, converted to the
        wallet's currency (`*Nanos` = billionths of a currency unit, so
        `236250000000` nanos INR is ₹236.25). filter by a digit `pattern` or a
        `city`.
      operationId: searchAvailableNumbers
      parameters:
        - name: pattern
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 15
                pattern: ^[0-9]*$
              - type: 'null'
          description: digits the number should contain, e.g. an area prefix like `8046`.
        - name: city
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 64
              - type: 'null'
          description: filter by city, e.g. `Bangalore`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 20
            minimum: 1
            default: 20
          description: page size (1–100, default 25).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: skip this many results.
      responses:
        '200':
          description: ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableNumberList'
              examples:
                default:
                  value:
                    items:
                      - number: '918046800123'
                        e164: '+918046800123'
                        prefix: '8046'
                        city: Bangalore
                        region: Karnataka
                        country: India
                        numberType: local
                        subType: null
                        monthlyRentalRateUsd: '2.50000'
                        setupRateUsd: '0.00000'
                        voiceRateUsd: '0.00787'
                        voiceEnabled: true
                        restriction: null
                        restrictionText: null
                        monthlyRentNanos: 236250000000
                        setupNanos: 0
                        voiceRateNanos: 743715000
                        outboundRateUsd: '0.01000'
                        outboundRateNanos: 945000000
                        outboundUnitSeconds: 30
                        currency: INR
                    totalCount: 42
                    limit: 20
                    offset: 0
        '401':
          description: >-
            `unauthorized` — key missing, malformed, unknown, revoked or
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    error: Invalid API key
                    code: unauthorized
        '403':
          description: '`forbidden_scope` — the key was created without the `agent` scope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden_scope:
                  value:
                    error: This API key lacks the 'agent' scope
                    code: forbidden_scope
        '429':
          description: >-
            `rate_limited` — the key's per-minute budget is spent. `Retry-After`
            says how long to wait; the body carries `limit` and `current`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: Rate limit exceeded
                    code: rate_limited
                    limit: 100
                    current: 101
          headers:
            Retry-After:
              description: seconds to wait before retrying (per-key rate limit only).
              schema:
                type: integer
        '502':
          description: >-
            `telephony_plivo_error` — the carrier refused the request. safe to
            retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_plivo_error:
                  value:
                    error: The telephony provider rejected the request
                    code: telephony_plivo_error
        '503':
          description: >-
            `telephony_not_configured` — rented numbers are unavailable on this
            deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_not_configured:
                  value:
                    error: Phone number rental is not available right now
                    code: telephony_not_configured
components:
  schemas:
    AvailableNumberList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AvailableNumber'
          type: array
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
      type: object
      required:
        - items
        - totalCount
        - limit
        - offset
      title: AvailableNumberList
    Error:
      type: object
      properties:
        error:
          type: string
          description: human-readable error message.
        code:
          type: string
          description: machine-readable error code.
    AvailableNumber:
      properties:
        number:
          type: string
          description: bare digits — pass as `requestedNumber`.
        e164:
          type: string
          description: the same in E.164.
        prefix:
          anyOf:
            - type: string
            - type: 'null'
        city:
          anyOf:
            - type: string
            - type: 'null'
        region:
          anyOf:
            - type: string
            - type: 'null'
        country:
          anyOf:
            - type: string
            - type: 'null'
        numberType:
          anyOf:
            - type: string
            - type: 'null'
        subType:
          anyOf:
            - type: string
            - type: 'null'
        monthlyRentalRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        setupRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        voiceRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        voiceEnabled:
          type: boolean
          default: true
          description: whether the number can carry voice calls.
        restriction:
          anyOf:
            - type: string
            - type: 'null'
        restrictionText:
          anyOf:
            - type: string
            - type: 'null'
          description: any carrier restriction on the number.
        monthlyRentNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: monthly rent in the wallet's currency, nanos.
        setupNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: one-off setup fee, nanos.
        voiceRateNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: inbound per-minute rate, nanos.
        outboundRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        outboundRateNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: outbound per-minute rate, nanos, billed per `outboundUnitSeconds`.
        outboundUnitSeconds:
          anyOf:
            - type: integer
            - type: 'null'
        currency:
          anyOf:
            - type: string
            - type: 'null'
      type: object
      required:
        - number
        - e164
      title: AvailableNumber
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        your rumik api key, e.g. `rk_live_...`. create one in the rumik
        dashboard.

````