Local HTTP(S) API

SDK Open provides local Asset HTTP/HTTPS endpoints for input file upload and task asset access.

Site	URL	Notes
Asset HTTPS	https://sdk-runtime.localhost:18082	Default external SDK endpoint for file upload and task asset access.
Asset HTTP	http://127.0.0.1:17082	Plaintext compatibility endpoint.

The external SDK enables TLS by default and uses the local sdk-runtime.localhost domain. Override the Asset HTTP port with SDK_ASSET_HTTP_PORT and the Asset HTTPS port with SDK_ASSET_HTTPS_PORT. For custom TLS deployments, clients must use a <tls-host> that matches the server certificate and trust the server certificate or its issuing CA.

Asset URLs use the configured asset base URL. For HTTPS, reverse proxies, or a fixed external address, set SDK_ASSET_BASE_URL to the HTTPS base URL reachable by clients, for example https://sdk.example.com:18082.

Authenticated endpoints use:

Authorization: Bearer <token>

Upload and asset APIs use the session_token returned by auth.create_session.

The APIs support CORS preflight with Authorization and Content-Type request headers, and GET, POST, and OPTIONS methods.

Upload APIs

POST /api/uploads/images and POST /api/uploads/files accept multipart/form-data. The two paths currently share the same upload handler.

Auth requirement: Authorization: Bearer <session_token>. The session must have at least one of these capabilities: image.process, image.enhance, or file.convert.

Field	Type	Required	Notes
file	file	Yes	Image, PDF, OFD, or TIFF. The file must not be empty and must be no larger than 50MB.

Supported file extensions: jpg, jpeg, png, bmp, tif, tiff, webp, pdf, and ofd. When Content-Type is empty or application/octet-stream, the asset content_type is derived from the extension.

Success response:

Field	Type	Notes
upload_id	string	Upload ID used by later Command methods.
asset	object	Original asset with asset_id=asset-original and kind=original, including path, url, download_url, content_type, width, height, and size. Uploaded files can have width and height set to 0.

Example:

curl -X POST "https://sdk-runtime.localhost:18082/api/uploads/files" \
  -H "Authorization: Bearer <session_token>" \
  -F "file=@/path/to/input.pdf"

Response example:

{
  "upload_id": "img-1780920159-1",
  "asset": {
    "asset_id": "asset-original",
    "kind": "original",
    "path": "/home/user/.czur/sdk/image/img-1780920159-1/assets/original.pdf",
    "url": "https://sdk-runtime.localhost:18082/api/assets/img-1780920159-1/asset-original",
    "download_url": "https://sdk-runtime.localhost:18082/api/assets/img-1780920159-1/asset-original/download",
    "content_type": "application/pdf",
    "width": 0,
    "height": 0,
    "size": 102400
  }
}

Asset APIs

API	Auth	Notes
GET /api/assets/{task_id}/{asset_id}	session token	Reads the asset inline with Content-Disposition: inline.
GET /api/assets/{task_id}/{asset_id}/download	session token	Downloads the asset as an attachment with Content-Disposition: attachment; filename="{asset_id}".

Asset access validates the session_token connection and task ownership. Cross-connection reads return capability or session errors. Current asset read rules:

Asset source	Read requirement
Uploaded assets, image processing assets, file conversion assets, and SANE scan assets	Same connection, plus at least one of image.process, image.enhance, file.convert, or sane.scan.
Image enhancement task assets	Same connection, plus image.enhance.
Capture task assets	Same connection, plus capture.get.

If the asset record exists but the local file no longer exists, HTTP returns 404.

Error Responses

HTTP API errors use a common JSON shape:

{
  "code": 401,
  "message": "unauthorized",
  "data": {}
}

Common HTTP statuses:

HTTP Status	Scenario
400	Missing multipart file field, or uploaded file is empty, too large, or unsupported.
401	Missing or invalid session token.
403	The session exists but lacks the capability required for upload or asset access.
404	Upload or asset API unavailable, or asset not found.
500	Internal error.