HTTP API

The web plugin also exposes all of its functions through a REST-ish API. You can use it to write small scripts or even for a full-blown Android or iPhone application, if you feel so inclined.

GET /api/remote/templates

Get option templates for all available plugins from a remote server.

Behaves exactly like GET /api/templates.

Query Parameters:
 
  • server – Hostname of remote server
Response Headers:
 
GET /api/remote/discover

Get list of available postprocessing servers on network.

Response Headers:
 
Request JSON Object:
 
  • servers (array) – List of available server addresses
POST /api/system/shutdown

Shut down device.

Requires that the user running the application has permission to run shutdown -h now via sudo. Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.

GET /api/remote/plugins

Get available plugin names from a remote server, grouped by type.

Behaves exactly like GET /api/plugins.

Query Parameters:
 
  • server – Hostname of remote server
Response Headers:
 
GET /api/remote/config

Get default configuration from a remote server.

Behaves exactly like GET /api/config.

Query Parameters:
 
  • server – Hostname of remote server
Response Headers:
 
POST /api/system/reboot

Reboot device.

Requires that the user running the application has permission to run shutdown -r now via sudo. Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.

GET /api/templates

For every activated plugin, get all option templates.

Response Headers:
 
POST /api/workflow

Create a new workflow.

Request Headers:
 
Request JSON Object:
 
  • config (object) – Configuration for new workflow
  • metadata (object) – Metadata for new workflow
Response Headers:
 
Status Codes:
  • 200 OK – When everything was OK.
  • 400 Bad Request – When validation of configuration or metadata failed.
GET /api/workflow

Return a list of all workflows.

Response Headers:
 
GET /api/plugins

Get names of available and activated postprocessing and output plugins.

Response Headers:
 
Response JSON Object:
 
  • postprocessing (array) – List of postprocessing plugin names
  • output (array) – List of output plugin names
GET /api/config

Get global default configuration.

Response Headers:
 
PUT /api/config

Update global default configuration.

If core or web settings were modified, the application will be restarted.

Request Headers:
 
Response Headers:
 
POST /api/reset

Restart the application.

Note that this endpoint will never send a response, clients should take this into account and set a low timeout value.

GET /api/isbn

Search for ISBN records.

Query Parameters:
 
  • q – Search query
Response Headers:
 
Response JSON Object:
 
  • results (array) – Matching ISBN records
Status Codes:
GET /api/log

Get application log.

Query Parameters:
 
  • start – Index of first message (default: 0)
  • count – Number of messages to return (default: 50)
  • level – Maximum log level to be included in messages (default: INFO)
Response Headers:
 
Response JSON Object:
 
  • total_num (boolean) – Total number of messages
  • messages (array) – Requested messages
GET /api/workflow/(workflow: workflow)/page/(int: number)/(img_type)/thumb
GET /api/workflow/(workflow: workflow)/page/(int: number)/(img_type)/(plugname)/thumb

Get thumbnail for a page image.

POST /api/workflow/(workflow: workflow)/page/(int: number)/(img_type)/crop

Crop a page image in place.

GET /api/workflow/(workflow: workflow)/page/(int: number)/(img_type)
GET /api/workflow/(workflow: workflow)/page/(int: number)/(img_type)/(plugname)

Get image for requested page.

Parameters:
  • workflow (str) – UUID or slug for a workflow
  • number (int) – Capture number of requested page
  • img_type (str, one of raw or processed) – Type of image
  • plugname (str) – Only applicable if img_type is processed, selects the desired processed file by its key in the spreads.workflow.Workflow.processed_images dictionary.
Query Parameters:
 
  • width – Optionally scale down image to the desired width
  • format – Optionally convert image to desired format. If browser is specified, non-JPG or PNG images will be converted to PNG.
Response Headers:
 
  • Content-Type – Depends on value of format, by default the mime-type of the original image.
GET /api/workflow/(workflow: workflow)/output/(fname)

Download an output file.

Parameters:
  • workflow (str) – UUID or slug for the workflow to download from
  • fname (str) – Filename of the output file to download
Status Codes:
GET /api/workflow/(workflow: workflow)/page/(int: number)

Get a single page.

Parameters:
  • workflow (str) – UUID or slug for a workflow
  • number (int) – Capture number of requested page
Response Headers:
 
DELETE /api/workflow/(workflow: workflow)/page/(int: number)

Remove a single page from a workflow.

POST /api/workflow/(workflow: workflow)/prepare_capture

Prepare capture for the requested workflow.

POST /api/workflow/(workflow: workflow)/finish_capture

Wrap up capture process on the requested workflow.

GET /api/workflow/(workflow: workflow)/download
Redirect to download endpoint (see
spreadsplug.web.handlers.ZipDownloadHandler or spreadsplug.web.handlers.TarDownloadHandler) with proper filename set.
Parameters:
  • workflow (str) – UUID or slug for the workflow to download
Query Parameters:
 
  • fmt – Archive format for download (zip or tar, default: tar)
Status Codes:
  • 302 Found – Redirects to GET /api/workflow/(str:workflow_id)/download/(str:workflow_slug).(str:archive_extension)
POST /api/workflow/(workflow: workflow)/transfer

Enqueue workflow for transfer to an attached USB storage device.

Requires that the python-dbus package is installed.

Once the transfer was succesfully enqueued, watch for the spreadsplug.web.tasks.on_transfer_started which is emitted when the transfer actually started and subsequently spreadsplug.web.tasks.on_transfer_progressed and spreadsplug.web.tasks.on_transfer_completed.

Parameters:
  • workflow (str) – UUID or slug for the workflow to be transferred
Status Codes:
POST /api/workflow/(workflow: workflow)/capture

Trigger a capture on the requested workflow.

Optional parameter ‘retake’ specifies if the last shot is to be retaken.

Returns the number of pages shot and a list of the pages captured by this call in JSON notation.

POST /api/workflow/(workflow: workflow)/process

Enqueue the specified workflow for postprocessing.

POST /api/workflow/(workflow: workflow)/submit

Enqueue workflow for submission to a postprocessing server.

It is possible to submit a configuration object that should be used on the remote end for the workflow. Optionally, it can be specified if postprocessing and output generation should immediately be enqueued on the remote server.

Once the submission was succesfully enqueued, watch for the spreadsplug.web.tasks.on_submit_started which is emitted when the submission actually started and subsequently spreadsplug.web.tasks.on_submit_progressed, spreadsplug.web.tasks.on_submit_completed and spreadsplug.web.tasks.on_submit_error.

Request Headers:
 
Parameters:
  • workflow (str) – UUID or slug for the workflow to be submitted
Request JSON Object:
 
  • server (string) – Address of server to submit to
  • config (object) – Configuration to use for workflow on remote server.
  • start_process (boolean) – Whether to enqueue workflow for post-processing on the remote server.
  • start_output (boolean) – Whether to enqueue workflow for output generation on the remote server.
Status Codes:
POST /api/workflow/(workflow: workflow)/output

Enqueue the specified workflow for output generation.

GET /api/workflow/(workflow: workflow)/page

Get all pages for a workflow.

Parameters:
  • workflow (str) – UUID or slug for a workflow
Response Headers:
 
DELETE /api/workflow/(workflow: workflow)/page

Delete multiple pages from a workflow with one request.

GET /api/workflow/(workflow: workflow)

Return a single workflow.

Parameters:
  • workflow (str) – UUID or slug for a workflow
Response Headers:
 
PUT /api/workflow/(workflow: workflow)

Update a single workflow.

Parameters:
  • workflow (str) – UUID or slug for the workflow to be updated
Request JSON Object:
 
  • config (object) – Updated workflow configuration
  • metadata (object) – Updated workflow metadata
Response Headers:
 
Status Codes:
  • 200 OK – When everything was OK.
  • 400 Bad Request – When validation of configuration or metadata failed.
DELETE /api/workflow/(workflow: workflow)

Delete a single workflow from database and disk.

Parameters:
  • workflow (str) – UUID or slug for the workflow to be updated
Status Codes:
  • 200 OK – When deletion was succesful
GET /api/isbn/(isbn)

Get metadata for a given ISBN number.

Parameters:
  • isbn (str/unicode with valid ISBN-10 or ISBN-13, optionally prefixed with isbn:) – ISBN number to retrieve metadata for
Response Headers:
 
Status Codes:
  • 200 OK – When the ISBN was valid and a match was found.
  • 400 Bad Request – When the ISBN was invalid or no match was found.
GET /static/(path: filename)

Function used internally to send static files from the static folder to the browser.

New in version 0.5.