--- slug: espaco-de-trabalho/arquivos title: Arquivos description: Envie, organize e recupere arquivos da organização. sidebar: order: 2 --- Os arquivos pertencem à organização e permanecem nela quando seus membros mudam. Peça ao agente para enviar documentos e planilhas e organizar o acesso em pastas. ## Cota de armazenamento [#storage-quota] O espaço da organização está em [Ativação e limites](/docs/espaco-de-trabalho/limites). Os dados processados para consulta de planilhas têm uma cota separada. - **`limitBytes`**: capacidade de armazenamento da organização. - **`usedBytes`**: arquivos ativos e na lixeira. Os bytes são liberados após a exclusão definitiva. - **`reservedBytes`**: espaço reservado por uploads em andamento. - **Espaço disponível**: `limitBytes - usedBytes - reservedBytes`. Mover um arquivo para a lixeira mantém seus bytes contabilizados. Restaurá-lo durante o prazo de recuperação não consome espaço adicional. ## Envio pelo agente [#chunking-reservations] O agente envia cada arquivo por MCP neste fluxo: 1. **Reserve o envio com `upload_begin`.** Informe `requestId`, `name`, `mediaType` e `size`, além do destino quando necessário. O servidor confere a cota, reserva o tamanho declarado e devolve o envio e `transfer`: um link de uso único (`url`), o cabeçalho `Upload-Token` e `command`, um `curl` pronto. 2. **Envie o arquivo.** O agente roda `transfer.command` no terminal, com `FILE` trocado pelo caminho local. O `PUT` leva só o `Upload-Token`, nunca o token da conexão. A resposta é o envio concluído (`kind: "completed"`); o id do arquivo é `file.id`. O servidor confere o tamanho, ativa o arquivo e converte o espaço reservado em usado. Repetir o `PUT` depois de concluído devolve o mesmo arquivo. 3. **Acima de 64 MiB, envie em partes.** Mande cada parte de 8 MiB (8.388.608 bytes) com `PUT {url}?part=N`, N de 1 em diante; a última parte leva o restante. O envio termina quando a última parte chega. O link vale por uma hora (até `transfer.expiresAt`) e age como a conexão que o criou: se ela for revogada ou a pessoa sair da organização, o link para de funcionar. Chamar `upload_begin` de novo com o mesmo `requestId` devolve um link novo para o mesmo envio. São permitidas até 10.000 partes: no máximo 83.886.080.000 bytes por arquivo (78,125 GiB), dentro do espaço disponível da organização. No Codex, o `curl` precisa de rede; veja [Conectar Codex](/docs/agentes/instalar/codex#uploads). Use o mesmo `requestId` (até 200 caracteres) ao repetir uma tentativa. Outro nome, destino ou tamanho com a mesma chave falha com `conflict`; em `file_write` e `sheet_write`, outros bytes também entram nessa verificação. `upload_cancel` cancela um envio inacabado e libera a reserva. Uploads abandonados expiram e são limpos automaticamente. Cada ferramenta lista seus parâmetros completos no schema de entrada; veja [MCP](/docs/agentes/mcp#tools-reference). ## Lixeira e recuperação [#trash-recovery] `trash` move um arquivo ativo para a lixeira por 30 dias. Ele sai da listagem padrão e aparece em `list` com `state: "trash"`. `restore` recupera o arquivo antes de `recover_until`. Pelo MCP, exige `files:write` e acesso de escrita ao item. Após o prazo, a restauração fica indisponível e a limpeza automática exclui os dados. Nenhum agente apaga um item na hora: qualquer membro com acesso de escrita move para a lixeira e restaura, e a Siglata apaga o item 30 dias depois, liberando os bytes após a remoção dos dados armazenados. `activity_list` registra quem moveu o item, por qual agente e quando, e também o apagamento. ## Renomear e baixar [#metadata-operations] `rename` altera o nome sem copiar o conteúdo ou consumir mais espaço. `file_read` devolve o conteúdo na resposta até 128 KiB e dois caminhos de download: - **`link`**: endereço do Console para uma pessoa autenticada abrir no navegador. - **`transfer`**: um link de uso único para o próprio agente salvar o arquivo, com o cabeçalho `Download-Token` e `command`, um `curl` pronto que grava o arquivo com o nome dele na pasta de trabalho. O link vale por 10 minutos e serve um único download. O download age como a conexão que chamou `file_read`: antes de enviar os bytes, ele confere a conexão, o vínculo com a organização e o acesso ao arquivo, e fica registrado na Atividade. ## Pastas e Controle de Acesso [#folders-access] Arquivos podem residir em pastas aninhadas, e cada arquivo e pasta carrega um atributo `visibility`: - **`org`** (padrão): Os membros podem acessá-lo, respeitando as restrições das pastas e os escopos OAuth. A escrita no [espaço da empresa](/docs/espaco-de-trabalho/empresa#access) também exige as permissões descritas lá. - **`restricted`**: Somente o criador do objeto, membros `owner`/`admin` da organização e membros com concessão explícita, direta ou por uma equipe da qual fazem parte, podem acessar o objeto. Uma pasta restrita restringe toda a sua subárvore: para ler ou gravar um objeto, o chamador precisa satisfazer cada pasta restrita na cadeia de ancestrais. Uma concessão em uma pasta se estende aos seus descendentes irrestritos, enquanto um objeto restrito dentro de uma pasta compartilhada ainda exige sua própria concessão. - Operações negadas falham com o código de erro `forbidden`; objetos restritos que um membro não pode ler também são omitidos dos resultados de `list`. - `grant_set` é limitado ao criador do objeto e a administradores da organização; define o nível de um beneficiário, e `level: null` o revoga. As operações de compartilhamento existem só para organizações Empresas. - Uma concessão vai para um membro (`granteeType: "user"`) ou para uma [equipe](/docs/espaco-de-trabalho/organizacoes#teams) (`granteeType: "team"`) da organização; qualquer outro id falha com `invalid_input`. A concessão de uma equipe vale para quem é membro dela a cada requisição: quem sai da equipe perde o acesso na requisição seguinte. Com uma concessão direta e outra por equipe, vale o nível mais alto. - `set_visibility`, como `grant_set`, é limitado ao criador do objeto e a administradores da organização; uma concessão de escrita não basta. Não altera concessões existentes. - `move` e `upload_begin` em uma pasta requerem acesso de escrita à pasta de destino. - Mover uma pasta para a lixeira não move seu conteúdo; quando uma pasta na lixeira ultrapassa o prazo de recuperação, ela é excluída e seus filhos voltam para a raiz da organização.