API REFERENCE · Batches and files
Authorize a direct private Blob upload
Complete request parameters, body fields, response formats, examples, and errors for POST /uploads/intent.
Base URL: https://www.sanctionskit.com/api/v1. Documentation examples are saved and require no API key to read.
POST/uploads/intentAuthorize a direct private Blob upload
Authentication: Authorization: Bearer YOUR_API_KEY (required). Use a server-side key for the intended environment and scopes.
Required API key scope: batches:write.
Request parameters
- Path parameters
- None.
- Query parameters
- None.
- Headers
Authorization(required)- JSON body fields
sizeBytes
Send JSON body fields as application/json, not as query parameters. Field definitions and nested properties follow below.
Request body
Optional body. JSON properties belong in the request body, separately from headers and URL parameters.
JSON request body. Send Content-Type: application/json with UTF-8 encoding; fields marked required must be present. Omit optional fields unless needed. Null is accepted only where explicitly shown. Unknown properties are rejected for validated request objects. Duplicate keys and nesting beyond 32 levels are rejected. Maximum body size: 1,048,576 bytes (1 MiB).
application/jsonView UploadIntentRequest schemaRequest body fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
sizeBytesOptional- integer
Exact UTF-8 byte size of the NDJSON upload. Maximum 26,214,400 bytes (25 MiB). Omission reserves the full maximum for legacy clients. The entire body may also be omitted.
Minimum: 1. Maximum: 26214400.
Additional fields are not accepted.
Example request
{
"sizeBytes": 1048576
}Responses
201Successful response. JSON object with the required data key. All properties marked required are present, including keys whose value may be null. Unmarked properties can be omitted; clients should tolerate additional response properties.
Response headers
X-Request-Id- string
Server-generated request correlation identifier.
Format: uuid.
application/jsonResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
dataRequired- objectView UploadIntent schema
data fields and rules
dataRequired.id - string
Format: uuid.
dataRequired.pathname - string
dataRequired.access - "private"
Must equal "private".
dataRequired.handleUploadUrl - "/api/v1/uploads"
Must equal "/api/v1/uploads".
dataRequired.maxBytes - integer
Minimum: 0.
dataRequired.reservedBytes - integer
Minimum: 0.
dataRequired.format - string
Example response
Synthetic contract example, validated against the response schema. Invented data; no live customer, provider request, payment, message or source activation.
{
"data": {
"id": "01234567-89ab-4cde-8f01-23456789abcd",
"pathname": "org/org_example/sandbox/uploads/01234567-89ab-4cde-8f01-23456789abcd.jsonl",
"access": "private",
"handleUploadUrl": "/api/v1/uploads",
"maxBytes": 26214400,
"reservedBytes": 26214400,
"format": "One screening request JSON object per line, at most 10000 rows."
}
}400invalid_request — Correct the request fields, resource identifiers, JSON body or query parameters before retrying.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Correct the request fields, resource identifiers, JSON body or query parameters before retrying.
{
"error": {
"code": "invalid_request",
"message": "The request is invalid.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}401authentication_required — Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key. invalid_api_key — Use an active key for the intended environment.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
WWW-Authenticate- string
Bearer authentication challenge.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.
{
"error": {
"code": "authentication_required",
"message": "Sign in to continue.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}invalid api key
Synthetic error example. Use an active key for the intended environment.
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid, expired, or revoked.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}402subscription_required — Use the synthetic sandbox or arrange an active production subscription before retrying.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Use the synthetic sandbox or arrange an active production subscription before retrying.
{
"error": {
"code": "subscription_required",
"message": "An active subscription is required for production screening.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}403permission_denied — Ask an organization owner to grant the required role or API-key scope. insufficient_scope — Use a key with the scope stated in this operation.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Ask an organization owner to grant the required role or API-key scope.
{
"error": {
"code": "permission_denied",
"message": "Your role does not allow this action.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}insufficient scope
Synthetic error example. Use a key with the scope stated in this operation.
{
"error": {
"code": "insufficient_scope",
"message": "The API key does not grant this action.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}405method_not_allowed — Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
Allow- string
Comma-separated supported HTTP methods.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.
{
"error": {
"code": "method_not_allowed",
"message": "This method is not supported for this endpoint.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}408invalid_request — Reconnect and retry using the same idempotency key and identical input where supported.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Reconnect and retry using the same idempotency key and identical input where supported.
{
"error": {
"code": "invalid_request",
"message": "The request body was not received within 10 seconds.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}413response_too_large — Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated. invalid_request — Reduce the JSON request size to the documented limit.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.
{
"error": {
"code": "response_too_large",
"message": "This response exceeds the size limit. Request a smaller page or a segmented export.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}invalid request
Synthetic error example. Reduce the JSON request size to the documented limit.
{
"error": {
"code": "invalid_request",
"message": "REQUEST_TOO_LARGE",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}415invalid_request — Use Content-Type: application/json and an uncompressed UTF-8 body.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Use Content-Type: application/json and an uncompressed UTF-8 body.
{
"error": {
"code": "invalid_request",
"message": "Send application/json with UTF-8 encoding.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}429rate_limited — Wait for the request window to reset and retry with backoff. upload_quota_exceeded — Wait for expired uploads to be deleted before requesting another upload intent.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
Retry-After- string
When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Wait for the request window to reset and retry with backoff.
{
"error": {
"code": "rate_limited",
"message": "The per-minute request limit has been reached.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}upload quota exceeded
Synthetic error example. Wait for expired uploads to be deleted before requesting another upload intent.
{
"error": {
"code": "upload_quota_exceeded",
"message": "This workspace has reached its upload storage limit. Capacity becomes available after expired uploads are deleted.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}500internal_error — Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.
{
"error": {
"code": "internal_error",
"message": "The request could not be completed.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}503temporarily_unavailable — Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.
Response headers
X-Request-Id- string
Server-generated correlation identifier, also returned in error.requestId.
Format: uuid.
Retry-After- string
When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.
application/jsonView Error schemaResponse fields
Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.
Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
errorRequired- object
error fields and rules
errorRequired.code - string
Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
errorRequired.message - string
Human-readable explanation. Do not parse this text to control application behavior.
errorRequired.requestId - string
Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
Format: uuid.
errorOptional.details - object[] or object or string or number or boolean or null
Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
error.details fields and rules
Allowed alternatives
- object[]
Maximum items: 50.
Each array item: object.
errorRequired.details[] .path - string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
errorRequired.details[] .message - string
Validation problem for this field.
Maximum length: 300.
- object
Additional keys are allowed; their values are not a fixed contract.
- string or number or boolean or null
May be null.
- object[]
errorOptional.detailsTruncated - boolean
True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
Example response
Synthetic error example. Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.
{
"error": {
"code": "temporarily_unavailable",
"message": "The service is temporarily unavailable. Retry shortly.",
"requestId": "01234567-89ab-4cde-8f01-23456789abcd"
}
}