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

# Arquivos

> Objeto asset: campos, relacionamentos e eventos.

Um `asset` é um item da biblioteca: **arquivo ou vídeo**. O mesmo objeto nunca contém as duas variantes preenchidas. A criação reserva um envio direto; depois de enviar o conteúdo, confirme o upload e acompanhe o processamento até `ready`.

## Objeto completo

Formato retornado pelas consultas e pelos itens das listagens. Os campos de retorno não são todos editáveis; confira as regras de escrita abaixo.

```json theme={null}
{
  "id": "ast_1234567890abcdef",
  "created_at": "2030-01-01T00:00:00.000Z",
  "description": null,
  "file": {
    "checksum": null,
    "filename": "material.pdf"
  },
  "metadata": {},
  "mime_type": "application/pdf",
  "object": "asset",
  "size_bytes": null,
  "status": "uploading",
  "title": "Material de apoio",
  "type": "file",
  "updated_at": "2030-01-01T00:00:00.000Z",
  "video": null
}
```

### Variante de vídeo

Em um vídeo, `file` é `null` e `video` contém os dados de processamento. Os campos desconhecidos podem ser `null` durante o envio.

```json theme={null}
{
  "id": "ast_1234567890abcdef",
  "created_at": "2030-01-01T00:00:00.000Z",
  "description": null,
  "file": null,
  "metadata": {},
  "mime_type": null,
  "object": "asset",
  "size_bytes": 104857600,
  "status": "ready",
  "title": "Aula de introdução",
  "type": "video",
  "updated_at": "2030-01-01T00:00:00.000Z",
  "video": {
    "duration_seconds": 600,
    "height": 1080,
    "progress": 100,
    "width": 1920
  }
}
```

## Campos do objeto

**id** `string`

Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes.

**created\_at** `string`

Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.

**description** `string | null`

Descrição do item. Pode ser null; envie null para limpar.

**file** `object | null`

Detalhes do arquivo quando type é file. Null para vídeos. Somente leitura.

**Campos de file**

**checksum** `string | null`

Checksum do arquivo, quando disponível; null quando não informado.

**filename** `string`

Nome original do arquivo, incluindo a extensão.

**metadata** `object`

Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use `{}` para limpar. Não aceita null.

**mime\_type** `string | null`

Tipo MIME do arquivo, como application/pdf. Pode ser null. Informado no início do upload de arquivo; não é editável depois.

**object** `string`

Tipo do objeto retornado. O valor é fixo para este recurso.

Sempre `asset`.

**size\_bytes** `integer | null`

Tamanho do conteúdo em bytes, preenchido pela verificação/processamento. Pode ser null enquanto desconhecido. Somente leitura.

**status** `string`

Estado do envio: uploading, processing, ready ou failed. deleted indica exclusão; itens excluídos não aparecem nas consultas normais. Somente leitura.

Valores: `uploading`, `processing`, `ready`, `failed`, `deleted`.

**title** `string`

Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload.

**type** `string`

Variante do conteúdo: file ou video. Definida pela operação de criação e não editável.

Valores: `file`, `video`.

**updated\_at** `string`

Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.

**video** `object | null`

Detalhes do vídeo quando type é video. Null para arquivos. Somente leitura.

**Campos de video**

**duration\_seconds** `integer | null`

Duração do vídeo em segundos; null enquanto desconhecida.

**height** `integer | null`

Altura do vídeo em pixels; null enquanto desconhecida.

**progress** `number | null`

Percentual de processamento informado, de 0 a 100; pode ser null.

**width** `integer | null`

Largura do vídeo em pixels; null enquanto desconhecida.

## Criação e alterações

Use [Iniciar upload de arquivo](https://docs.hubfy.io/api-reference/assets/create-file.md) com `title` e `filename`, ou [Iniciar upload de vídeo](https://docs.hubfy.io/api-reference/assets/create-video.md) com `title`. A resposta é o objeto `asset` completo, acrescido do campo `upload` com a credencial de envio. Siga o [fluxo de upload e download](https://docs.hubfy.io/api-reference/assets/uploads.md).

Depois de criado, apenas `description`, `metadata` e `title` são editáveis. O tipo e os dados de processamento são preenchidos pela Hubfy. Downloads privados exigem um arquivo pronto e devolvem uma URL válida por uma hora. Excluir marca o item como removido e agenda a limpeza do conteúdo.

Campos omitidos em uma atualização são preservados. `metadata` substitui o objeto inteiro quando enviado. Campos desconhecidos são rejeitados.

## Relacionamentos

`file` e `video` são partes do mesmo asset, não recursos independentes. O vínculo de entrega com produtos e cursos é administrado no painel.

## Eventos

* [`asset.created`](https://docs.hubfy.io/api-reference/webhooks/asset.created)
* [`asset.updated`](https://docs.hubfy.io/api-reference/webhooks/asset.updated)
* [`asset.deleted`](https://docs.hubfy.io/api-reference/webhooks/asset.deleted)

Envio, confirmação e processamento podem gerar `asset.updated`.

Eventos descrevem mudanças efetivas no objeto público. Repetir uma operação sem alterar o objeto não garante um evento. Confira [entrega e assinatura](https://docs.hubfy.io/api-reference/webhooks/delivery.md).


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