CURL Examples

The following examples use the Linux curl program to interface with the CirrusPrint server API.  These examples all use the API key for authorization, and assume that key is stored in an environment variable CPAPI.  They interface with a hypothetical server, cp.example.com, using the default https port -- your actual server may also require a :port suffix to the hostname, such as mycp.example.com:27083.

Note that when curl is supplied -d or --data type arguments, by default it will submit the request with content type "application/x-www-form-urlencoded", as is expected by the API.

Any errors are reported with a plain text response starting with "Error: ".

Job Managment

Submit a Job to a Device

This sends a file x.pdf to a specified device, additionally supplying a job title.  The curl -T option uses a PUT method to upload the file.  The field arguments must be supplied as a query string, so the -G option is used to generate the query string from the -data fields.  You could alternatively include the url-encoded query string in the url, appending "?targets=User1:browser&title=Test%20Title".

curl -H "Authorization: Bearer $CPKEY" \

 -T x.pdf \

 -G --data-urlencode "targets=User1:browser" \

 --data-urlencode "title=Test Title" \

 https://cp.example.com/api/putfile

A successful response is one or more job numbers, separated by linefeeds.  In this case, a single target resulted in a single job:

20220318185808-1

Upload a File, Submit the File

This method enables you to upload a file, then submit it multiple times using different options.  This sequence of curl commands follows these steps.  This example will use gzip compression, so the uploaded content is gzipped first, then cmp=2 is used when submitting the file, so the server will decompress the file content using that method.

1. Compress and upload the file

gzip documents.pdf

tempfile=`curl -H "Authorization: Bearer $CPKEY" -T documents.pdf.gz  https://cp.example.com/api/putfile`

The response will be a temporary file name, for use in the following steps.  To see this response:

echo $tempfile produces something like this: putfile_172.30.0.210_200736.0632-1.dat

2. Submit file to User1's browser:

curl -H "Authorization: Bearer $CPKEY" \

 --data-urlencode "file=$tempfile" \

 --data-urlencode "title=Document List" \

 --data-urlencode "targets=User1:browser" \

 --data "cmp=2" \

 https://cp.example.com/api/submitfile

3. Submit file to a file to a printer device:

curl -H "Authorization: Bearer $CPKEY" \

 --data-urlencode "file=$tempfile" \

 --data "cmp=2" \

 --data-urlencode "title=Document List" \

 --data-urlencode "targets=Loc1:hp2320" \

 --data-urlencode "props=copies=3;scale=2" \

 https://cp.example.com/api/submitfile

For details about standard properties for printers, see Output Devices.

The responses to the /api/submitfile request are one or more job numbers, separated by linefeeds.

Get a Job Status

The above submission calls return job numbers.  These job numbers can be used to obtain job status for as long as the job remains available on the server.  For jobs sent to a location client device, the job will remain available for status for a number of hours.  Jobs sent to browser clients remain in place for longer unless the user deletes them from their trash folder.

curl -H "Authorization: Bearer $CPKEY" "https://cp.example.com/api/get/job/Demo/User1/browser/20220318185808-1?pretty"

This returns a JSON response for the job 20220318185808-1 sent to company Demo, location User1, device browser.  The result looks something like this:

{

  "Name": "Test Title",

  "Submitted": "2022-03-18T21:34:53.541030

  "Size": 46662,

  "MimeType": "application/pdf",

  "Ext": "pdf",

  "State": 1,

  "Segments": {

    "1": [

      0,

      46662

    ]

  },

  "SrcID": "@api",

  "LocID": "User1",

  "DevID": "browser",

  "Properties": {},

  "RawPrint": false,

  "ForceCRLF": false,

  "Target": "",

  "Received": "2022-03-18T21:34:55.107Z",

  "Delivered": "2022-03-18T21:34:55.107Z",

  "Message": "",

  "Updated": 1647639297138681300,

  "SrcName": ""

}

Configuration Management

Get a Location Record

This can be executed as a simple URL with the authorization header.  The "pretty" field in the query string makes the JSON response easier to read.  In the URL, "Demo" is the company ID and Loc1 is the location ID.

curl -H "Authorization: Bearer $CPAPI" "https://cp.example.com/api/get/location/Demo/Loc1?pretty"

The successful response is a JSON formatted string with all the location's data, similar to this:

{

  "LocID": "Loc1",

  "Name": "",

  "Password": "loc1",

  "IsInactive": false,

  "Type": 0,

  "AllowFrom": [],

  "Email": "",

  "Email2": "",

  "Phone": "",

  "Printers": [

    "Universal Printer\tGhostscript PDF universalport:\t;\t1\t1\t0\tLetter,A4",

    "Sales-HP2320\tMicrosoft PCL6 Class Driver devlin_9204\t;\t0\t0\t0",

    "Sales Lexmark\tMicrosoft PCL6 Class Driver devlin_9205\t;\t0\t0\t0",

    "Inhouse9901\tMicrosoft PCL6 Class Driver inhouse-9201\t;\t0\t0\t0",

    "Dev-LexT640\tMicrosoft PCL6 Class Driver devlin_9203\t;\t0\t0\t0",

    "Dev-HP200\tMicrosoft PCL6 Class Driver devlin_9200\t;\t0\t0\t0"

  ],

  "Devices": {

    "dev-hp200": {

      "DevID": "Dev-Hp200",

   ... more data follows ...

Put a Location Record

This requires adding form fields for the fields you want to update.  When updating an existing record, only supply the fields you want to change.  Field names are not case-sensitive.  This example updates Loc1 in the Demo company.

curl -H "Authorization: Bearer $CPAPI" \

  --data-urlencode "name=Location One" \

  --data "type=0" \

  --data-urlencode "password=Apple&123" \

  "https://cp.example.com/api/put/location/Demo/Loc1"

The successful response is a JSON formatted string of the updated record.

Delete a Location Record

A simple URL deletes a location record:

curl -H "Authorization: Bearer $CPAPI" "https://cp.example.com/api/delete/location/Demo/Loc1"

A successful response is any empty one.  On errors are reported with a message.

List Location Records

curl -H "Authorization: Bearer $CPAPI" "https://cp.example.com/api/list/locations/Demo?csv"

A successful response will be a CSV-formatted list of locations records.  Note that the printers array elements, which in JSON contains tab-separated values, contain pipe-separated values.

Put a Device Record

This will add or update an output device, such as a printer.  Device records reside under a Location, so to create a device record you  must identify its location as part of the URL structure.

curl -H "Authorization: Bearer $CPAPI" \

  --data-urlencode "name=HP 2000 Printer" \

  --data "type=0" \

  --data-urlencode "target=Sales-HP2000" \

  --data-urlencode "formats=pcl5;pcl6" \

  --data-urlencode "defaultprops=copies=1;scale=2" \

  "https://cp.example.com/api/put/device/Demo/Loc1/HP2000"

The successful response is a JSON formatted string of the updated record.

Create a Site User for use with Open ID Connect

This will create/update a site user "testid", including their OIDC user ID from the third party provider.

curl -H "Authorization: Bearer $CPSITEAPI" \

 --data-urlencode "name=Test User" \

 --data-urlencode "email=someone@example.com" \

 --data "isadmin=true" \

 --data "password=!" \

 --data-urlencode "oidcuserid=auth0|12345" \

 "https://cp.example.com/api/put/siteuser/testid"