POST/v1/uploads
Iniciar um upload em partes
create_upload
Abre uma sessão de upload para um arquivo grande (até o limite da instalação para uploads em partes, 5 GB por padrão): o nome, o tipo de conteúdo, o tamanho e o purpose, que indica o que vai usar o upload: card_file (POST /v1/cards), archive (POST /v1/cards/archive) ou import_attachment (um anexo de um documento de fonte personalizada). A resposta tem o id (upl_ seguido de 32 caracteres hexadecimais), o tamanho das partes part_size e o número de partes part_count. Todas as partes, exceto a última, têm exatamente part_size bytes (de 5 a 100 MiB), e a última parte é o restante. Um upload incompleto fica disponível por 24 horas (expires_at).
Uma extensão do nome do arquivo fora dos formatos da finalidade retorna 415 uploads.unsupported_format (um anexo de importação aceita qualquer extensão). Um arquivo maior que o limite da instalação ou que o armazenamento total da organização no plano dela retorna 413 uploads.too_large. A falta de armazenamento disponível, contando os uploads incompletos da organização, retorna 402 limits.storage.
As partes passam pelo Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) e são criptografadas com a chave da organização no armazenamento de arquivos; não há links diretos para o armazenamento. Só a chave de API ou o usuário que criou o upload pode vê-lo e usá-lo. Adicionado na versão 1.62.0.
Autenticação
Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.
Parâmetros de cabeçalho
Idempotency-KeystringChave para uma nova tentativa segura de uma gravação: de 1 a 255 caracteres ASCII imprimíveis; recomenda-se um UUID v4 por operação lógica. Uma nova tentativa com a mesma chave dentro de 24 horas não executa a operação de novo: retorna a resposta salva (status, cabeçalhos e corpo) com o cabeçalho
Idempotency-Replayed: true. A mesma chave com outro método, caminho,Content-Typeou corpo retorna409 api.idempotency_mismatch; enquanto a primeira requisição ainda está em execução,409 api.idempotency_in_progresscomRetry-After: 1. Depois de uma resposta 5xx ou 429, a chave é liberada, e uma nova tentativa executa a operação de novo. A chave vale para a organização e para quem faz a chamada (chave de API, usuário ou chave de fonte personalizada).length ≥ 1, length ≤ 255
Corpo da requisição
application/json
filenamestringobrigatórioO nome do arquivo com a extensão; a extensão define o formato.
length ≥ 1, length ≤ 255
content_typestringO tipo de conteúdo declarado (MIME); ele é comparado com a assinatura do arquivo.
length ≤ 255
sizeinteger (int64)obrigatórioO tamanho do arquivo em bytes.
≥ 1
sha256stringO SHA-256 do arquivo, se conhecido de antemão;
completecompara com ele a soma de verificação do arquivo.
Respostas
201A sessão de upload foi criada.
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
Idempotency-Replayedtruesignifica que a resposta foi reproduzida a partir da resposta salva para estaIdempotency-Key: a operação não foi executada de novo.
application/json
idstringobrigatórioO ID do upload (
upl_seguido de 32 caracteres hexadecimais).filenamestringobrigatórioO nome do arquivo (sem pastas).
content_typestringobrigatórioO tipo de conteúdo declarado; vazio se não foi declarado.
sizeinteger (int64)obrigatórioO tamanho do arquivo em bytes.
sha256string | nullobrigatórioO SHA-256 do arquivo, declarado na criação ou em
complete;nullse ainda não for conhecido.part_sizeinteger (int64)obrigatórioO tamanho de cada parte, exceto a última (de 5 a 100 MiB).
part_countintegerobrigatórioO número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobrigatórioO número de partes recebidas.
≥ 0
As partes recebidas, por número (vazio na resposta de
POST /v1/uploads).reject_reasonstring | nullobrigatórioO motivo da rejeição (
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. A enumeração pode crescer;nullse não houve rejeição.reject_detailsobject | nullobrigatórioDetalhes da rejeição (a extensão, o formato declarado e o detectado, as somas de verificação);
nullse não houve rejeição.created_atstring (date-time)obrigatórioQuando o upload foi criado.
expires_atstring (date-time)obrigatórioO prazo para concluir o upload e, depois que ele estiver pronto, para usá-lo.
completed_atstring (date-time) | nullobrigatórioQuando a conferência terminou (
readyourejected).consumed_atstring (date-time) | nullobrigatórioQuando o upload foi usado (por um cartão, um arquivo compactado ou uma importação).
401Nenhuma credencial foi enviada (nem cookie de sessão nem chave de API), ou a chave não foi encontrada.
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
402A organização atingiu um limite do plano (cartões, armazenamento ou usuários). `error.details` contém `kind`, `limit` e `used`.
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
403A ação não é permitida: a função é insuficiente, não há acesso à coleção ou ao cartão, a requisição é executada no modo “View as” ou a organização está suspensa ou excluída (`detail` é um objeto com `code: org_suspended | org_deleted`).
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
413O corpo da requisição excede o tamanho permitido.
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
415O formato do arquivo não é suportado.
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
422Erro de validação: o corpo ou os parâmetros não correspondem ao esquema (`detail` é uma lista de erros de validação), ou o valor de um parâmetro está fora do intervalo (`detail` é uma mensagem).
Cabeçalhos da resposta
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
429Requisições demais (`api.rate_limited`), a cota da organização para o minuto, o dia ou o mês se esgotou (`api.quota_exceeded`; `error.details` contém `quota`, `limit` e `reset_at`), o limite da organização foi atingido ou o serviço de respostas está ocupado (`answers.engine_busy`). Aguarde o tempo indicado no cabeçalho `Retry-After`.
Cabeçalhos da resposta
Retry-AfterNúmero de segundos a esperar antes de tentar a requisição novamente.
RateLimit-PolicyLimites em vigor, no formato do rascunho da IETF
draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula"<name>";q=<quota>;w=<window in seconds>.keyé a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão éuser, sem credenciais éip);minute,dayemonthsão as cotas da organização para o minuto, o dia e o mês do calendário em UTC.RateLimitO que resta de cada limite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLimite da entrada mais restritiva de
RateLimit-Policy(a que tem menos requisições restantes).X-RateLimit-RemainingRequisições restantes no limite mais restritivo.
X-RateLimit-ResetSegundos até o limite mais restritivo ser reiniciado.
application/json
Códigos de erro
Códigos que este endpoint pode retornar em error.code, além dos códigos gerais de qualquer requisição.
Novas tentativas seguras
Envie um cabeçalho Idempotency-Key (por exemplo, um UUID) em cada POST e PATCH. Uma nova tentativa com a mesma chave em até 24 horas retorna a resposta salva, em vez de executar a requisição de novo.
Limites de taxa
As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.