Uploads

A large file sent in chunks: the server counts received bytes, so a broken upload continues from there. The input of a bulk operation.

Loading the search index…

Uploads

Objects

Upload

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • file_namestringrequired

    Name of the file given when the upload started.

  • sizeintegerrequired

    Size of the whole file in bytes.

  • receivedintegerrequired

    Bytes received: the offset of the next chunk.

  • completebooleanrequired

    The file is assembled: a bulk operation can take it by id. After that the upload is gone.

  • chunk_bytesintegerrequired

    Largest size of one chunk in bytes.

  • expires_atstring (date-time)required

    After this moment an unused upload is deleted.

  • created_atstring (date-time)required

    When the record was created.

Endpoints

Get a chunked file upload: how much is received

get/uploads/{upload}

Scope: bulk:read

Parameters

Path

  • uploadintegerrequired

    ID of the upload.

Responses

200Success

application/json

Returns Upload

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl "https://api.saleya.app/v1/uploads/{upload}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "file_name": "string",
  "size": 0,
  "received": 0,
  "complete": true,
  "chunk_bytes": 0,
  "expires_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z"
}

Start a chunked file upload — the input of a bulk operation

post/uploads

Scope: bulk:write

Parameters

Header

  • Idempotency-Keystring

    Unique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.

    Min length:
    1
    Max length:
    255
    Example:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Request body application/json

  • file_namestringrequired

    Name of the file given when the upload started.

    Max length:
    255
  • sizeintegerrequired

    Size of the whole file in bytes.

    Minimum:
    1
    Maximum:
    268435456

Responses

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true

application/json

Returns Upload

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns ConflictProblem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X POST "https://api.saleya.app/v1/uploads" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "file_name": "string",
  "size": 1
}
Example response · 201
{
  "id": 0,
  "file_name": "string",
  "size": 0,
  "received": 0,
  "complete": true,
  "chunk_bytes": 0,
  "expires_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z"
}

Append a file chunk as the raw body

post/uploads/{upload}/chunks

Scope: bulk:write

Parameters

Path

  • uploadstringrequired

    ID of the upload.

Query

  • offsetintegerrequired

    Byte of the file the chunk starts at: equal to received of the upload, otherwise 409 upload_offset_mismatch. The chunk itself is the raw request body.

    Minimum:
    0

Header

  • Idempotency-Keystring

    Unique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.

    Min length:
    1
    Max length:
    255
    Example:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Request body application/octet-stream

string (binary)

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true

application/json

Returns Upload

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns ConflictProblem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X POST "https://api.saleya.app/v1/uploads/{upload}/chunks?offset=<offset>" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file
Example response · 200
{
  "id": 0,
  "file_name": "string",
  "size": 0,
  "received": 0,
  "complete": true,
  "chunk_bytes": 0,
  "expires_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z"
}