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

# Get a region

> Return one published region by its immutable code. Unknown and unpublished
regions both return 404. This public endpoint is rate-limited per client IP;
successful responses may be cached privately for 60 seconds.


<Info>
  Requires **no IAM action**. Access is decided by the endpoint's own
  rules rather than by a policy — see the description above.
</Info>


## OpenAPI

````yaml /api-reference/specs/catalog.yaml get /v1/regions/{code}
openapi: 3.0.3
info:
  title: Basaltic Catalog API
  version: 1.0.0
  description: >-
    Public global platform discovery. Lifecycle is independent of live health,
    capacity, tenant authorization, and product placement.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://catalog.basaltic.sh
    description: Global catalog endpoint
security: []
paths:
  /v1/regions/{code}:
    get:
      tags:
        - Regions
      summary: Get a region
      description: >
        Return one published region by its immutable code. Unknown and
        unpublished

        regions both return 404. This public endpoint is rate-limited per client
        IP;

        successful responses may be cached privately for 60 seconds.
      operationId: getRegion
      parameters:
        - name: code
          in: path
          required: true
          description: Immutable region code.
          schema:
            type: string
            pattern: ^[a-z][a-z0-9-]{0,31}$
            example: sa-saopaulo-1
      responses:
        '200':
          description: Published region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Region'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security: []
components:
  schemas:
    Region:
      type: object
      required:
        - crn
        - code
        - name
        - location
        - country_code
        - state
        - accepting_new_resources
        - available
        - coming_soon
      properties:
        state:
          type: string
          enum:
            - planned
            - active
            - restricted
            - retiring
            - retired
          description: >-
            Catalog lifecycle, independent of health and capacity. Retired codes
            are never reused.
          example: active
        accepting_new_resources:
          type: boolean
          description: >-
            True only for active regions. Product services still enforce
            eligibility, quotas, placement and capacity.
          example: true
        crn:
          type: string
          description: >-
            Platform-owned global region identity, using the immutable region
            code.
          example: crn:catalog::platform:region/sa-saopaulo-1
        code:
          type: string
          description: Unique region code used in API calls and CRNs
          example: sa-saopaulo-1
        name:
          type: string
          description: Human-readable region name
          example: São Paulo 1
        location:
          type: string
          description: Geographic location of the region
          example: São Paulo, Brazil
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code (used to display flag in UI)
          example: BR
          minLength: 2
          maxLength: 2
        available:
          type: boolean
          description: >-
            Compatibility alias for accepting_new_resources; not a live health
            signal
          example: true
        coming_soon:
          type: boolean
          description: Compatibility flag that is true only when state is planned
          example: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_INPUT
              message: Invalid request parameters
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
    TooManyRequests:
      description: >
        Rate limit exceeded. The budget is a fixed window counted per endpoint
        and

        per caller — the authenticated principal when the request carries

        credentials, the client IP otherwise — so one throttled endpoint never

        spends another's budget, and one tenant never spends another's.


        Wait `Retry-After` seconds, then retry. The `X-RateLimit-*` headers ride
        on

        the successful responses of a rate-limited endpoint too, so a client can

        pace itself instead of discovering the ceiling by hitting it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMITED
              message: Too many requests, please try again later
              request_id: 550e8400-e29b-41d4-a716-446655440000
      headers:
        Retry-After:
          description: Seconds to wait before retrying. Never zero.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 42
        X-RateLimit-Limit:
          description: Requests allowed per window on this endpoint.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 5
        X-RateLimit-Remaining:
          description: Requests left in the current window. Always 0 on a 429.
          required: true
          schema:
            type: integer
            minimum: 0
          example: 0
        X-RateLimit-Reset:
          description: >-
            Seconds until the window resets — a duration, not a timestamp, so it
            needs no clock agreement between client and server.
          required: true
          schema:
            type: integer
            minimum: 1
          example: 42
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000

````