Upload API

Upload é um recurso temporário criado ao enviar um arquivo. É o primeiro passo antes de criar um Media: ao enviar um arquivo, a resposta retorna um Upload, e com as informações desse Upload você cria o Media. A criação do Media ocorre na CMA (Weegloo User) ou na ACMA (Service User) e está fora do escopo desta página.

Upload é um recurso temporário. Ele expira 24 horas após a criação (expiresAt) e, se não for transformado em Media nesse prazo, desaparece. Upload não tem conceito de publicação nem de versão (não possui as propriedades version, status ou publish). Também não tem campos de corpo, contendo apenas as propriedades de sistema sys. A URL base é https://upload.weegloo.com/v1, e toda requisição exige um token Bearer que autentica o Upload.

Estrutura do recurso

A seguir está a resposta de um Upload em que uma foto de produto de uma loja de roupas (imagem de uma garrafa térmica) foi enviada a um Space. Há apenas sys, e dentro dele estão chaves como owner, expiresAt e size.

{
  "sys": {
    "id": "4bgMfu7cFGYDRQn4jdqFI8tkOWKZIm",
    "type": "Upload",
    "owner": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T04:48:44.057Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T04:48:44.057Z",
    "expiresAt": "2026-06-19T04:48:44.057Z",
    "size": 50847
  }
}

Principais chaves:

• sys.id: identificador único do Upload. Você passa esse valor ao criar o Media. Também entra no {uploadId} dos caminhos de consulta individual e exclusão.
• sys.owner: referência que aponta para o local ao qual este Upload pertence. O targetType é Space ou Organization (veja Contexto de Space e Organization abaixo).
• sys.expiresAt: instante de expiração. É 24 horas após createdAt; passado esse instante, o Upload desaparece.
• sys.size: tamanho do arquivo enviado (em bytes). O exemplo acima tem 50847 bytes.

Propriedades de sistema (sys)

Todo Upload mantém suas propriedades de sistema no objeto sys. owner, createdBy e updatedBy entram no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

As 9 propriedades acima estão sempre incluídas na resposta. As propriedades version, status e publish que existem no sys de Content ou Content Type não existem em Upload. Isso ocorre porque Upload não é um recurso que se publica ou versiona, e sim um material descartável usado uma única vez para criar o Media. O owner não aponta para um único tipo, como o space de outros recursos; conforme o targetType, ele aponta para Space ou Organization.

Contexto de Space e Organization

Upload pode ser criado em dois contextos, e o caminho e o sys.owner mudam conforme o contexto.

O Upload no contexto de Space é o material para criar o Media daquele Space. O Upload no contexto de Organization é usado para enviar arquivos aplicados diretamente à organização, como o ícone da organização. Em ambos os casos, a estrutura do recurso retornado na resposta é a mesma; apenas o valor de targetType em sys.owner é diferente.

Formas de envio: multipart e binary

A requisição POST que envia o arquivo tem duas formas. Em qualquer uma delas, o que retorna na resposta é o mesmo recurso Upload.

A forma multipart envia o corpo da requisição como multipart/form-data. O arquivo vai em um campo de formulário com o nome file. É adequada para situações em que se envia por dados de formulário, como no envio direto a partir do seletor de arquivos do navegador.

A forma binary coloca os bytes brutos do arquivo diretamente no corpo da requisição. Não há restrição quanto ao tipo de mídia do corpo (Content-Type) (normalmente se usa application/octet-stream) e, no contexto de Space, é preciso enviar também o comprimento em bytes do corpo no cabeçalho Content-Length. É adequada para código no lado do servidor que transmite apenas os bytes do arquivo, sem estrutura de formulário.

API

A URL base de todos os endpoints abaixo é https://upload.weegloo.com/v1, e o cabeçalho Authorization exige um token Bearer que autentica o Upload. Primeiro são tratados os 4 do contexto de Space e, em seguida, os 4 do contexto de Organization.

Documentos relacionados

• Media: formato de requisição para criar um Media a partir do Upload enviado.
• Media (conceito): como lidar com ativos de arquivo no estúdio de conteúdo.