Skip to content
Sursa Developers

GET/v1/uploads/{upload_id}

Get an upload

get_upload

Returns the upload status and the received parts (parts: the number, size, SHA-256 and ETag of each), so after a dropped connection the client sends only the missing parts. status: pending waits for parts and complete, processing means the file is being assembled and checked, ready means it can be used, rejected means it was rejected (reject_reason), consumed means it has already been used, and expired means its time ran out. Another caller's upload returns 404 uploads.not_found. Added in 1.62.0.

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Path parameters

  • upload_idstringrequired

    The upload ID (upl_ followed by 32 hex characters).

    length ≤ 64

Responses

200OK

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Upload

  • idstringrequired

    The upload ID (upl_ followed by 32 hex characters).

  • purposeUploadPurposerequired
  • filenamestringrequired

    The file name (without folders).

  • content_typestringrequired

    The declared content type; empty if not declared.

  • sizeinteger (int64)required

    The file size in bytes.

  • sha256string | nullrequired

    The SHA-256 of the file, declared at creation or at complete; null if not known yet.

  • statusUploadStatusrequired
  • part_sizeinteger (int64)required

    The size of each part except the last (from 5 to 100 MiB).

  • part_countintegerrequired

    The number of parts.

    ≥ 1, ≤ 1000

  • parts_receivedintegerrequired

    The number of received parts.

    ≥ 0

  • partsarray of UploadPartrequired

    The received parts by number (empty in the POST /v1/uploads response).

  • reject_reasonstring | nullrequired

    The rejection reason (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. The enumeration may grow; null if not rejected.

  • reject_detailsobject | nullrequired

    Details of the rejection (the extension, the declared and detected format, checksums); null if not rejected.

  • created_atstring (date-time)required

    When the upload was created.

  • expires_atstring (date-time)required

    The deadline to complete the upload and, once it is ready, to use it.

  • completed_atstring (date-time) | nullrequired

    When the check finished (ready or rejected).

  • consumed_atstring (date-time) | nullrequired

    When the upload was used (by a card, an archive or an import).

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

404The object does not exist or is not available to you. The API does not confirm that a restricted object exists.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

  • Retry-After

    Number of seconds to wait before you retry the request.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← uploads · API reference