Vision ScanBarcode Intelligence
Start evaluation

Cloud REST with Python

Call the experimental authenticated upload, job, and status HTTP API from Python; this is not an embedded Python scanner SDK.

Status
Experimental
Integration
Cloud REST client
Distribution
HTTP API
Version
0.1.0-RC4

Prerequisites

  • Python 3.11 or newer
  • requests
  • VISIONSCAN_CLOUD_URL
  • VISIONSCAN_ACCESS_TOKEN

1. Install the HTTP client

Install the HTTP client
python -m pip install requests

Use your normal dependency pinning and vulnerability scanning policy.

2. Create an authenticated session

Create an authenticated session
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['VISIONSCAN_ACCESS_TOKEN']}"})

Tenant and site are derived from the verified token; never send a tenant override.

3. Upload and submit

Upload and submit
upload = session.post(f"{base}/v1/uploads", json={"idempotencyKey": str(uuid.uuid4()), "contentBase64": base64.b64encode(image).decode(), "contentType": "image/png"}).json()
job = session.post(f"{base}/v1/jobs", json={"idempotencyKey": str(uuid.uuid4()), "uploadIds": [upload["uploadId"]], "profile": "still-image-dense"}).json()
status = session.get(f"{base}/v1/jobs/{job['jobId']}").json()

Call raise_for_status() after every request in production code.

Errors and recovery

ConditionResolution
409 idempotency conflictReuse a key only with the identical tenant-scoped payload; generate a new key for a changed request.
ENGINE_ADAPTER_UNAVAILABLEThe experimental service has no production engine adapter; do not interpret this as an empty scan.

Production checklist

  • Use a production RS256 token
  • Set connect and read timeouts
  • Bound image size before base64 encoding
  • Treat the API as experimental until production certification

Public contract reference

These are the callable methods and HTTP operations used by this guide. Inputs, results, lifecycle rules, and denial behavior are part of the versioned customer contract.

Cloud upload contract

Upload bytes are authenticated, bounded, MIME-checked, idempotent, and tenant-scoped.

POST /v1/uploads

http

Persist one validated image and return a tenant-scoped upload identifier.

Inputs for POST /v1/uploads
InputTypeRequiredMeaning
AuthorizationBearer tokenYesProduction RS256 token with bounded time claims and cloud-scan entitlement.
idempotencyKeyUUID/stringYesTenant-scoped key reused only for an identical retry.
contentBase64base64 stringYesLocally bounded PNG, JPEG, or WebP bytes.
contentTypestringYesimage/png, image/jpeg, or image/webp matching the file magic bytes.
Result
2xx JSON containing uploadId and non-sensitive upload metadata.
Lifecycle
Upload before creating a job; retain the idempotency key for retries of the same bytes.
Trust boundary
Tenant and site come only from the verified token; request bodies cannot override tenant scope.
Failure behavior
  • 401/403 for invalid or unentitled identity.
  • 409 for a reused key with different content.
  • 4xx for invalid MIME, magic bytes, base64, or size; 429 for quota limits.

Cloud job creation contract

A job references same-tenant uploads and selects a bounded scan profile.

POST /v1/jobs

http

Create an asynchronous scan job from one or more previously accepted uploads.

Inputs for POST /v1/jobs
InputTypeRequiredMeaning
idempotencyKeyUUID/stringYesTenant-scoped key for identical job retries.
uploadIdsstring[]YesExisting upload IDs owned by the authenticated tenant and site.
profilestringYesAn allowlisted profile such as still-image-dense.
callbackHTTPS URLNoOptional policy-validated callback; production delivery requires the documented callback controls.
Result
2xx JSON containing jobId, queued status, and correlation metadata.
Lifecycle
Create after uploads succeed, then poll status until completed or failed.
Trust boundary
Callbacks reject non-HTTPS and non-global destinations, pin validated addresses, follow no redirects, and HMAC-sign payloads.
Failure behavior
  • Cross-tenant or unknown uploads are denied.
  • 409 reports idempotency conflict; 429 reports quota pressure; invalid profiles fail validation.

Cloud job status contract

Status retrieval distinguishes completed, failed, and unavailable-engine outcomes from an empty scan.

GET /v1/jobs/{jobId}

http

Read the authenticated tenant's job state, receipt, structured error, and callback delivery state.

Inputs for GET /v1/jobs/{jobId}
InputTypeRequiredMeaning
jobIdpath stringYesThe job identifier returned by POST /v1/jobs.
AuthorizationBearer tokenYesThe same tenant/site scope that owns the job.
Result
JSON status that becomes completed or failed; completed identity evidence remains GTIN-first and preserves review-required OCR provenance.
Lifecycle
Poll with bounded backoff and stop on a terminal state.
Trust boundary
Do not log bearer tokens, encoded images, or sensitive receipt payloads; retain only non-sensitive correlation metadata.
Failure behavior
  • Cross-tenant and unknown identifiers do not expose another tenant's data.
  • ENGINE_ADAPTER_UNAVAILABLE is a failed job, not a successful scan with zero observations.
  • Unknown response shapes fail closed.

Review the release support matrix before deployment. Support status and contract failure behavior remain authoritative even when an example is copied.