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

# Listar imagens

> Listar apenas imagens pertencentes à conta selecionada. Use GET /v1/image-catalog para descobrir as imagens atuais de conta e plataforma inicializáveis. As imagens não podem ser tornadas públicas. A associação ao catálogo da plataforma é controlada por basalt:catalog=platform em imagens de propriedade da conta da plataforma.

Uma linha por tag. Uma compilação cai fora desta lista quando uma compilação *mais nova* mantém seu nome — histórico substituído, que permanece inicializável por id e por `name:version`. Qualquer coisa que ainda esteja importando ou com erro permanece listada independentemente de sua idade, e assim também uma versão estagiada com `current: false` que é mais nova que a atual. Passe `all_versions=true` para todo o histórico de uma tag.

As imagens retiradas são excluídas por padrão. Use `status=withdrawn` ou `all_versions=true` para inspecioná-los. Eles permanecem legíveis por ID, mas não podem ser usados para iniciar instâncias. A exclusão de imagens permanece legível até que a limpeza assíncrona seja concluída.


<Info>
  Requer a ação do IAM **`compute:ListImages`**. Consulte [permissões de computação](/pt/compute/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
</Info>


## OpenAPI

````yaml /pt/api-reference/specs/compute.yaml get /v1/images
openapi: 3.0.3
info:
  title: API de Basaltic Compute
  version: 1.0.0
  description: >
    Instâncias de máquina virtual e as imagens, os tipos e os pools de
    instâncias a partir dos quais elas são criadas. Abrange todo o ciclo de vida
    da instância: iniciar, parar, reiniciar, redimensionar e reinstalar.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://compute.{region}.basaltic.sh
    description: Endpoint de API regional
    variables:
      region:
        default: sa-saopaulo-1
        description: Código de região
security:
  - BearerAuth: []
paths:
  /v1/images:
    get:
      tags:
        - Images
      summary: Listar imagens
      description: >
        Listar apenas imagens pertencentes à conta selecionada. Use GET
        /v1/image-catalog para descobrir as imagens atuais de conta e plataforma
        inicializáveis. As imagens não podem ser tornadas públicas. A associação
        ao catálogo da plataforma é controlada por basalt:catalog=platform em
        imagens de propriedade da conta da plataforma.


        Uma linha por tag. Uma compilação cai fora desta lista quando uma
        compilação *mais nova* mantém seu nome — histórico substituído, que
        permanece inicializável por id e por `name:version`. Qualquer coisa que
        ainda esteja importando ou com erro permanece listada independentemente
        de sua idade, e assim também uma versão estagiada com `current: false`
        que é mais nova que a atual. Passe `all_versions=true` para todo o
        histórico de uma tag.


        As imagens retiradas são excluídas por padrão. Use `status=withdrawn` ou
        `all_versions=true` para inspecioná-los. Eles permanecem legíveis por
        ID, mas não podem ser usados para iniciar instâncias. A exclusão de
        imagens permanece legível até que a limpeza assíncrona seja concluída.
      operationId: listImages
      parameters:
        - $ref: '#/components/parameters/ComputeCRNFilter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
        - name: os
          in: query
          schema:
            type: string
            example: ubuntu
        - name: architecture
          in: query
          schema:
            type: string
            example: amd64
        - name: name
          in: query
          description: >-
            Correspondência de nome exata, diferenciando maiúsculas e
            minúsculas; um valor vazio não corresponde a nenhum recurso nomeado.
          schema:
            type: string
            example: ubuntu-24.04
        - name: status
          in: query
          schema:
            type: string
            enum:
              - pending
              - importing
              - active
              - error
              - deleting
              - withdrawn
            example: active
        - name: all_versions
          in: query
          description: >-
            Incluir compilações que uma versão mais recente substituiu.
            Desligado por padrão, quando cada tag contribui apenas com a
            compilação que vale a pena iniciar.
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: Uma página de imagens, ordenadas por nome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    ComputeCRNFilter:
      name: crn
      in: query
      description: >-
        CRN exato do recurso, intersetado com todos os outros filtros antes da
        paginação. Um CRN estrangeiro ou não correspondido retorna uma página
        vazia; CRNs malformados ou vazios retornam 400. As listas de anexos
        aninhadas filtram o recurso representado, não a vinculação.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: >-
        Número máximo de itens a devolver. Um valor acima do máximo é fixado ao
        invés de rejeitado, então uma página mais curta do que a que você pediu
        é normal — page until `meta.has_more` é false, não até que uma página
        pareça curta.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Marker:
      name: marker
      in: query
      description: >-
        Cursor de paginação opaco. Echo back o valor `meta.marker` da página
        anterior para buscar a próxima; não construa ou analise-o. A forma
        interna do token varia de acordo com o endpoint (um ID de recurso, um
        carimbo de data/hora, etc.) e não é garantida a estabilidade entre
        versões.
      required: false
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    ImageListResponse:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - images
    Image:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          example: >-
            crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901
        name:
          description: >-
            Os nomes de recursos não devem começar com o prefixo literal crn: ou
            ser UUIDs (formas canônicas, compactas, entre colchetes ou
            urn:uuid:, em qualquer caso).
          type: string
          example: ubuntu-24.04
        description:
          type: string
          example: Ubuntu 24.04 LTS (Noble Numbat)
        os:
          type: string
          example: ubuntu
        os_version:
          type: string
          example: '24.04'
        architecture:
          type: string
          example: amd64
        version:
          type: string
          description: >
            A identidade da compilação dentro de seu nome. Único lá: um nome é
            uma tag móvel, então não pode ser também o que diz duas construções
            separadas. Carimbado como um timestamp UTC quando o carregador não
            escolheu um.
          example: '20260807'
        is_current:
          type: boolean
          description: >
            Se esta é a versão resolve-by-name retorna para o seu (nome,
            arquitetura) — i.e. o alvo de tag atual do nome.
          example: true
        eol_date:
          type: string
          format: date
          description: >
            O dia em que a versão do SO desta imagem para de receber
            atualizações de segurança gratuitas para uma instalação padrão.
            Ausente quando ninguém registrou um — o que significa desconhecido,
            não "suportado indefinidamente".


            As imagens da plataforma são retiradas do catálogo após um período
            de carência após essa data. Eles permanecem inicializáveis por id
            até então, e a data é publicada bem antes para que você possa
            planejar a mudança.
          example: '2026-08-31'
        size_bytes:
          type: integer
          format: int64
          example: 2361393152
        min_disk_gb:
          type: integer
          minimum: 0
          maximum: 16384
          example: 10
        min_ram_mb:
          type: integer
          minimum: 0
          example: 1024
        status:
          type: string
          enum:
            - pending
            - importing
            - active
            - error
            - deleting
            - withdrawn
          description: >-
            Erro exatamente enquanto uma falha de erro ativo existe; o progresso
            de importação e exclusão permanecem independentemente retentáveis.
          example: active
        withdrawal_reason:
          type: string
          description: >
            Por que esta imagem foi retirada. Presente para imagens retiradas,
            incluindo aquelas com uma falha de erro independente: end_of_life
            para retirada de lançamento de plataforma (veja eol_date), ou legado
            para uma retirada migrada cuja razão original é desconhecida. As
            imagens retiradas retêm seus dados, mas não podem ser lançadas.
          example: end_of_life
        deletion_retention:
          type: object
          readOnly: true
          description: >
            Apresentar em respostas de lista de proprietários/detalhes enquanto
            a exclusão de imagem está esperando por referências de instância
            existente, reserva de origem ou pool de instâncias. As contagens
            incluem todas as contas de referência sem divulgar suas identidades.
            Os dados de backup permanecem intactos; a limpeza retoma quando as
            referências desaparecem. Falhas independentes ainda podem definir o
            status para erro.
          required:
            - reason
            - instances
            - instance_pools
          properties:
            reason:
              type: string
              enum:
                - in_use
            instances:
              type: integer
              minimum: 0
            instance_pools:
              type: integer
              minimum: 0
        faults:
          type: array
          readOnly: true
          description: >-
            Falhas ativas, mais recentes primeiro. Vazio para uma imagem
            saudável. As falhas de erro definem o status como erro sem
            desabilitar uma reintentância de importação ou limpeza elegível.
          items:
            $ref: '#/components/schemas/Fault'
        tags:
          $ref: '#/components/schemas/Tags'
        attributes:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T09:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T09:30:00Z'
      required:
        - id
        - crn
        - name
        - version
        - architecture
        - status
        - faults
        - created_at
        - updated_at
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Número total de itens
          example: 150
        limit:
          type: integer
          description: Número de itens por página
          example: 20
        marker:
          type: string
          description: >-
            Cursor opaco para a próxima página. Passe-o de volta como o
            parâmetro de consulta `marker`; trate-o como um token, não um valor
            para analisar.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Se há mais itens
          example: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Código de erro identificando o tipo de erro
              example: INVALID_INPUT
            message:
              type: string
              description: Mensagem de erro legível pelo ser humano
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Valores não sensíveis opcionais para interpolação de erros
                localizados, codificados por código de erro. Nunca presente para
                erros de servidor.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Solicitar ID para depuração
              example: 550e8400-e29b-41d4-a716-446655440000
    Fault:
      type: object
      required:
        - code
        - severity
        - message
        - details
        - first_at
        - last_at
        - occurrences
      properties:
        code:
          type: string
          description: >-
            Código estável legível por máquina pertencente à operação de
            relatório.
          example: BACKUP_FAILED
        severity:
          type: string
          enum:
            - error
            - warning
        message:
          type: string
          example: Backup upload failed.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Contexto estruturado; cadeias de caracteres legadas são preservadas
            em legacy_text.
        first_at:
          type: string
          format: date-time
          description: Primeira observação nesta série de ocorrências ativas.
        last_at:
          type: string
          format: date-time
          description: Última observação nesta série de ocorrências ativas.
        occurrences:
          type: integer
          minimum: 1
          example: 1
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
  responses:
    BadRequest:
      description: Parâmetros de solicitação inválidos
      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: Autenticação necessária ou token inválido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Permissões insuficientes
      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: Erro interno do servidor
      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: >+
        Um token bearer OAuth 2.0, enviado como `Authorization: Bearer <token>`.
        Esta é a forma recomendada de autenticação.


        Obtenha o token trocando o par de chaves de acesso de uma conta de
        serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
        Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
        com OAuth podem obter e renovar o token para você.


        ```

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


        Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
        também serve como credencial AWS SigV4 para o endpoint de objetos
        compatível com S3, que aceita somente esse método de autenticação.


````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.