> ## 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.

# List the launch image catalog

> Returns current active images categorized as platform or account. Platform
entries must be owned by the platform account and carry basalt:catalog=platform.
The same tag on an account image does not share it with other accounts.
Each name/architecture appears once, using its current build. Staged,
superseded, importing, failed, deleting and withdrawn builds are excluded.
Tags and operational metadata are omitted. Categories may expand in the
future (for example apps); clients should handle unfamiliar category names.
Pagination applies across all entries, ordered by name and id. Both current
categories are present on every page, even when one has no entries.


<Info>
  Requires the IAM action **`compute:ListImages`**. See [COMPUTE permissions](/compute/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/compute.yaml get /v1/image-catalog
openapi: 3.0.3
info:
  title: Basaltic Compute API
  version: 1.0.0
  description: |
    Virtual machine instances, and the images, flavors, SSH keypairs and
    instance pools they are built from. Covers the whole instance lifecycle:
    start, stop, reboot, resize and reinstall.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://compute.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
paths:
  /v1/image-catalog:
    get:
      tags:
        - Images
      summary: List the launch image catalog
      description: >
        Returns current active images categorized as platform or account.
        Platform

        entries must be owned by the platform account and carry
        basalt:catalog=platform.

        The same tag on an account image does not share it with other accounts.

        Each name/architecture appears once, using its current build. Staged,

        superseded, importing, failed, deleting and withdrawn builds are
        excluded.

        Tags and operational metadata are omitted. Categories may expand in the

        future (for example apps); clients should handle unfamiliar category
        names.

        Pagination applies across all entries, ordered by name and id. Both
        current

        categories are present on every page, even when one has no entries.
      operationId: listImageCatalog
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - name: name
          in: query
          description: Exact image name.
          schema:
            type: string
        - name: os
          in: query
          schema:
            type: string
        - name: architecture
          in: query
          schema:
            type: string
      responses:
        '200':
          description: One page of categorized current images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageCatalogResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: >-
        Maximum number of items to return. A value above the maximum is clamped
        to it rather than rejected, so a page shorter than the one you asked for
        is normal — page until `meta.has_more` is false, not until a page looks
        short.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Marker:
      name: marker
      in: query
      description: >-
        Opaque pagination cursor. Echo back the `meta.marker` value from the
        previous page to fetch the next one; do not construct or parse it. The
        token's internal form varies by endpoint (a resource ID, a timestamp, …)
        and is not guaranteed stable across releases.
      required: false
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    ImageCatalogResponse:
      type: object
      additionalProperties: false
      required:
        - categories
        - meta
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ImageCatalogCategory'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ImageCatalogCategory:
      type: object
      additionalProperties: false
      required:
        - name
        - images
      properties:
        name:
          type: string
          description: >-
            Catalog category. Currently platform or account; future categories
            may include apps.
          example: platform
        images:
          type: array
          items:
            $ref: '#/components/schemas/CatalogImage'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 150
        limit:
          type: integer
          description: Number of items per page
          example: 20
        marker:
          type: string
          description: >-
            Opaque cursor for the next page. Pass it back as the `marker` query
            parameter; treat it as a token, not a value to parse.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Whether there are more items
          example: true
    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
    CatalogImage:
      type: object
      additionalProperties: false
      description: >-
        Launch metadata for the current active build of an image name and
        architecture. No tags, build history, or operational metadata are
        exposed.
      required:
        - id
        - crn
        - name
        - architecture
        - min_disk_gb
        - min_ram_mb
      properties:
        id:
          type: string
          format: uuid
        crn:
          type: string
        name:
          type: string
        os:
          type: string
        os_version:
          type: string
        architecture:
          type: string
        min_disk_gb:
          type: integer
        min_ram_mb:
          type: integer
        eol_date:
          type: string
          format: date
  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
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````