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.
Uploads
Objects
Upload
idintegerrequiredID of the record, unique among records of its kind in the store.
file_namestringrequiredName of the file given when the upload started.
sizeintegerrequiredSize of the whole file in bytes.
receivedintegerrequiredBytes received: the offset of the next chunk.
completebooleanrequiredThe file is assembled: a bulk operation can take it by id. After that the upload is gone.
chunk_bytesintegerrequiredLargest size of one chunk in bytes.
expires_atstring (date-time)requiredAfter this moment an unused upload is deleted.
created_atstring (date-time)requiredWhen the record was created.
Endpoints
Get a chunked file upload: how much is received
get/uploads/{upload}
Scope: bulk:read
Parameters
Path
uploadintegerrequiredID of the upload.
Responses
200Success
application/json
Returns Upload
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication 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-AuthenticatestringAuthentication 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-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds 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
curl "https://api.saleya.app/v1/uploads/{upload}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"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-KeystringUnique 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_namestringrequiredName of the file given when the upload started.
- Max length:
- 255
sizeintegerrequiredSize of the whole file in bytes.
- Minimum:
- 1
- Maximum:
- 268435456
Responses
201Created
Headers
Idempotent-Replayedstringtrue 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-AuthenticatestringrequiredAuthentication 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-AuthenticatestringAuthentication 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-AfterintegerSeconds 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-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/uploads" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"file_name": "string",
"size": 1
}{
"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
uploadstringrequiredID of the upload.
Query
offsetintegerrequiredByte 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-KeystringUnique 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-Replayedstringtrue 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-AuthenticatestringrequiredAuthentication 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-AuthenticatestringAuthentication 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-AfterintegerSeconds 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-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
upload_offset_mismatchThe chunk does not start where expected - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
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{
"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"
}