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

# Descrever imagem

> Resolve tag ou digest para uma imagem e seu manifesto. `manifest` contém JSON interpretado, inadequado para verificar o digest porque a serialização pode reordenar chaves. Obtenha os bytes originais em `/v2` para verificar o hash.

<Info>
  Exige a ação IAM **`registry:BatchGetImage`**. Veja [REGISTRY permissões](/pt/registry/permissions) para a lista completa, o escopo de cada ação e um exemplo de política.
</Info>


## OpenAPI

````yaml /pt/api-reference/specs/registry.yaml get /v1/repositories/{repository_id}/images/{image_reference}
openapi: 3.0.3
info:
  title: API Basaltic Registry
  version: 1.0.0
  description: >-
    Registry de imagens de contêiner. A API de gerenciamento usa
    `registry.<region>.basaltic.sh`; Docker e clientes OCI usam
    `cr.<region>.basaltic.cloud`. Esta referência descreve `/v1`, autenticado
    por OAuth ou sessão do console. `/v2` segue a especificação OCI Distribution
    1.1.


    `POST /v1/authorization-token` gera uma senha para `docker login`, que a
    troca por tokens por repositório em `/v2/token`. A senha dura 12 horas, mas
    decisões de autorização usam as políticas atuais e tokens de cinco minutos.
    Referências de imagem incluem o identificador da conta; use a `uri`
    retornada pelo servidor.


    Blobs e manifestos são imutáveis e identificados por SHA-256. Tags são
    apontadores mutáveis, salvo com `tag_mutability: immutable`. Excluir por
    digest remove manifesto e tags; excluir por tag preserva o manifesto.
    Camadas são deduplicadas em toda a conta. `size_bytes` conta blobs
    distintos, e a coleta em segundo plano libera os que nenhuma imagem ainda
    usa.


    Uma política de recurso permite acesso entre contas ou público. Acesso entre
    contas exige autorização tanto no recurso como no IAM do chamador.


    `kms_key` aceita UUID, nome na conta ou CRN de uma chave simétrica
    habilitada na mesma conta e região. Referências inválidas retornam 400;
    chaves inexistentes retornam 404. Respostas usam ResourceRef e preservam ID
    e CRN sem nome quando a chave foi excluída.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://registry.{region}.basaltic.sh
    description: Endpoint de API regional
    variables:
      region:
        default: sa-saopaulo-1
        description: Código de região
security:
  - BearerAuth: []
tags:
  - name: Authorization
    description: Credencial usada por `docker login`
  - name: Repositories
    description: Ciclo de vida, configurações, imagens e tags dos repositórios
  - name: Policies
    description: Políticas de recurso e de ciclo de vida
  - name: Encryption
    description: Criptografia de camadas em repouso
  - name: Pull-through cache
    description: Cache de imagens de outro registry no seu namespace
paths:
  /v1/repositories/{repository_id}/images/{image_reference}:
    parameters:
      - $ref: '#/components/parameters/RepositoryId'
      - $ref: '#/components/parameters/Reference'
    get:
      tags:
        - Repositories
      summary: Descrever imagem
      description: >-
        Resolve tag ou digest para uma imagem e seu manifesto. `manifest` contém
        JSON interpretado, inadequado para verificar o digest porque a
        serialização pode reordenar chaves. Obtenha os bytes originais em `/v2`
        para verificar o hash.
      operationId: describeImage
      responses:
        '200':
          description: Imagem e manifesto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    RepositoryId:
      name: repository_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    Reference:
      name: image_reference
      in: path
      required: true
      description: Tag ou digest `sha256:`.
      schema:
        type: string
        example: v1.4.2
  schemas:
    ImageResponse:
      type: object
      properties:
        image:
          $ref: '#/components/schemas/Image'
        manifest:
          type: object
          description: >-
            Manifesto interpretado como JSON. Não use para verificar o digest,
            que depende dos bytes originais. Obtenha o manifesto em `/v2` para
            recalcular o hash.
      required:
        - image
    Image:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID da imagem, usado como cursor de paginação na listagem.
        digest:
          type: string
          description: SHA-256 dos bytes exatos do manifesto.
          example: >-
            sha256:1f3c9e0b8d7a6f5e4c3b2a190807f6e5d4c3b2a1908f7e6d5c4b3a2019f8e7d6c
        media_type:
          type: string
          description: >-
            Tipo de mídia OCI ou Docker v2, preservado como enviado. Ambos
            representam documentos equivalentes com rótulos diferentes.
          example: application/vnd.oci.image.manifest.v1+json
        tags:
          type: array
          items:
            type: string
          description: Todas as tags deste manifesto. Vazio para imagem sem tags.
          example:
            - v1.4.2
            - latest
        artifact_type:
          type: string
          description: >-
            Tipo do artefato: distingue imagem de contêiner, chart Helm, SBOM ou
            assinatura, todos armazenados como manifestos.
          example: application/vnd.oci.image.config.v1+json
        config_digest:
          type: string
          description: >-
            Ausente em um índice multiplataforma, que não tem configuração
            própria.
        subject:
          type: string
          description: >-
            Digest ao qual uma assinatura, SBOM ou atestação se refere. Usado
            pela API OCI de referências.
        manifest_size_bytes:
          type: integer
          format: int64
          description: Documento do manifesto.
        size_bytes:
          type: integer
          format: int64
          description: >-
            Soma dos blobs distintos referenciados pelo manifesto: o tamanho da
            imagem.
          example: 87654321
        is_index:
          type: boolean
          description: True para índice multiplataforma ou lista de manifestos Docker.
        pushed_at:
          type: string
          format: date-time
        last_pulled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Precisão de um minuto para evitar atualizações concorrentes por cada
            pull. Regras de ciclo de vida usam dias.
      required:
        - id
        - digest
        - media_type
        - tags
        - size_bytes
        - is_index
        - pushed_at
    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
  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
    NotFound:
      description: Página não encontrada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              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.