API Documentation - Olin Cloud Print

Introduction

Welcome to the Olin Cloud Print API documentation. This RESTful API allows you to integrate our enterprise print management system into your applications. You can submit print jobs, monitor printer status, manage queues, and access real-time analytics.

All API requests must be authenticated using your API token. The API returns JSON responses and uses standard HTTP response codes.

Authentication

The API uses Bearer token authentication. Include your API token in the Authorization header of every request.

Authorization: Bearer YOUR_API_TOKEN

Note: You can find your API token in your dashboard under Account Settings → API Token.

Base URL

https://cloudprint.olininnovations.co.ke/api

Response Format

All API responses follow a consistent JSON structure with a success indicator, message, and data payload.

Success Response

{
  "success": true,
  "message": "Operation successful",
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "message": "Error description",
  "errors": {
    // Validation errors (if applicable)
  }
}

Authentication Endpoints

POST /api/login

Authenticate a user and receive an API token.

Request Body

{
  "email": "user@example.com",
  "password": "your_password"
}

Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "name": "John Doe",
    "email": "user@example.com",
    "plan": "professional",
    "available_print_jobs": 450,
    "used_print_jobs": 50,
    "token": "your_api_token_here",
    "user_id": 1
  }
}

POST /api/register

Register a new user account or create a sub-account under an integrator.

Request Parameters

Field	Type	Required	Description
`name`	string	Yes	Full name (max 255 characters)
`email`	string	Yes	Valid email address (must be unique)
`password`	string	Yes	Password (min 8 characters)
`password_confirmation`	string	Yes	Must match password
`parent_api_key`	string	No	Parent integrator's API key (for sub-account creation)

Sub-Account Creation: To create a sub-account under an integrator account, include the parent's API key in the parent_api_key field. The parent account must:

Be an integrator account (Enterprise plan)
Have available sub-account slots (max 50 sub-accounts)

Example 1: Normal Account Registration

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "secure_password",
  "password_confirmation": "secure_password"
}

Example 2: Sub-Account Registration (with parent API key)

{
  "name": "Office Branch",
  "email": "branch@example.com",
  "password": "secure_password",
  "password_confirmation": "secure_password",
  "parent_api_key": "1|abc123parent_api_token_here"
}

Success Response

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "name": "John Doe",
    "email": "user@example.com",
    "plan": "free",
    "available_print_jobs": 10,
    "used_print_jobs": 0,
    "token": "your_api_token_here",
    "user_id": 1
  }
}

Error Responses

Invalid Parent API Key (401)

{
  "success": false,
  "message": "Invalid parent API key"
}

Parent Not Integrator (403)

{
  "success": false,
  "message": "Parent account must be an integrator account"
}

Sub-Account Limit Reached (403)

{
  "success": false,
  "message": "Parent account has reached the maximum limit of 50 sub-accounts"
}

User Endpoints

GET /api/user

Get authenticated user information.

Authentication Required: This endpoint requires a valid Bearer token.

Response

{
  "success": true,
  "message": "User data retrieved successfully",
  "data": {
    "name": "John Doe",
    "email": "user@example.com",
    "plan": "professional",
    "available_print_jobs": 450,
    "used_print_jobs": 50,
    "token": "your_api_token_here",
    "user_id": 1
  }
}

Printer Endpoints

GET /api/printers

Get all printers for the authenticated user, grouped by computer name.

Response

{
  "success": true,
  "data": {
    "DESKTOP-ABC123": [
      {
        "id": 1,
        "printer_id": "abc123",
        "name": "HP LaserJet Pro",
        "computer_name": "DESKTOP-ABC123",
        "location": "Office",
        "status": "available",
        "capabilities": {...},
        "last_seen_at": "2024-01-15 10:30:00"
      }
    ]
  },
  "total_printers": 1,
  "computers": ["DESKTOP-ABC123"],
  "message": "Printers retrieved successfully"
}

POST /api/printers/sync

Sync printer list from client application.

Request Body

{
  "printers": [
    {
      "printer_id": "abc123",
      "name": "HP LaserJet Pro",
      "computer_name": "DESKTOP-ABC123",
      "location": "Office",
      "status": "available",
      "capabilities": {
        "supports_color": true,
        "supports_duplex": true,
        "paper_sizes": ["A4", "Letter"]
      }
    }
  ]
}

POST /api/printers/heartbeat

Send periodic printer status updates.

Request Body

{
  "computer_name": "DESKTOP-ABC123",
  "timestamp": "2024-01-15T10:30:00Z",
  "printers": [
    {
      "name": "HP LaserJet Pro",
      "status": "available",
      "computer_name": "DESKTOP-ABC123",
      "location": "Office",
      "last_seen_at": "2024-01-15T10:30:00Z",
      "capabilities": {...}
    }
  ]
}

POST /api/printers/{printer}/test-page

Print a test page to verify printer functionality.

Response

{
  "success": true,
  "message": "Test page submitted successfully",
  "data": {
    "print_job": {...},
    "message": "Test page queued for printing"
  }
}

Print Job Endpoints

POST /api/print-jobs

Submit a new print job. Supports three input methods: direct file upload, base64-encoded file, or file URL.

File Input Methods: You must provide exactly ONE of the following:

file - Direct file upload (multipart/form-data)
file_base64 - Base64-encoded file content (JSON)
file_url - URL to download file from (JSON)

Request Parameters

Field	Type	Required	Description
`file`	file	One of three*	Direct file upload (max 10MB)
`file_base64`	string	One of three*	Base64-encoded file content
`file_url`	string	One of three*	URL to download file from
`file_name`	string	No	Original filename (for base64/URL uploads)
`printer_id`	integer	No	Target printer ID
`printer_name`	string	No	Printer name (if printer_id not provided)
`copies`	integer	No	Number of copies (1-99, default: 1)
`priority`	integer	No	Priority level (0-10, default: 0)
`print_options[color]`	boolean	No	Color printing (default: true)
`print_options[duplex]`	string	No	none, horizontal, vertical (default: none)
`print_options[paper_size]`	string	No	A4, Letter, Legal (default: A4)

Supported File Types:

Documents: PDF, DOC, DOCX, ODT, RTF
Images: JPG, PNG, GIF, BMP, TIFF, WebP
Text: TXT, HTML
Other: XPS

Example 1: Direct File Upload (multipart/form-data)

curl -X POST https://cloudprint.olininnovations.co.ke/api/print-jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "printer_id=1" \
  -F "copies=2" \
  -F "priority=5" \
  -F "print_options[color]=true" \
  -F "print_options[duplex]=horizontal" \
  -F "print_options[paper_size]=A4"

Example 2: Base64-Encoded File (JSON)

curl -X POST https://cloudprint.olininnovations.co.ke/api/print-jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iaiA8P...",
    "file_name": "document.pdf",
    "printer_name": "HP LaserJet Pro",
    "copies": 2,
    "priority": 5,
    "print_options": {
      "color": true,
      "duplex": "horizontal",
      "paper_size": "A4"
    }
  }'

Example 3: File URL (JSON)

curl -X POST https://cloudprint.olininnovations.co.ke/api/print-jobs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/documents/invoice.pdf",
    "file_name": "invoice.pdf",
    "printer_name": "Office Printer",
    "copies": 1,
    "print_options": {
      "color": false,
      "duplex": "none",
      "paper_size": "Letter"
    }
  }'

Response

{
  "success": true,
  "message": "Print job submitted successfully",
  "data": {
    "print_job": {
      "id": 123,
      "user_id": 1,
      "printer_id": 1,
      "printer_name": "HP LaserJet Pro",
      "original_name": "document.pdf",
      "status": "pending",
      "priority": 5,
      "print_options": {
        "copies": 2,
        "color": true,
        "duplex": "horizontal",
        "paper_size": "A4"
      },
      "submitted_at": "2024-01-15T10:30:00Z"
    },
    "download_url": "https://cloudprint.olininnovations.co.ke/api/print-jobs/123/download"
  }
}

POST /api/print-jobs/pending

Get pending print jobs (polling endpoint for client applications).

Response

{
  "success": true,
  "message": "Jobs retrieved successfully",
  "data": [
    {
      "id": 123,
      "fileName": "document.pdf",
      "printerName": "HP LaserJet Pro",
      "fileUrl": "https://cloudprint.olininnovations.co.ke/api/print-jobs/123/download",
      "file_base64": null,
      "is_base64": false,
      "file_source_url": "https://example.com/documents/invoice.pdf",
      "file_source_type": "url",
      "printerId": 1,
      "userId": 1,
      "status": "pending",
      "createdAt": "2024-01-15 10:30:00"
    }
  ]
}

Note: The response includes file_source_type which indicates how the file was submitted: direct_upload, base64, or url. For base64 files, file_base64 contains the encoded content. For other types, fileUrl provides the download endpoint. The file_source_url field is only populated when the file was submitted via URL.

GET /api/print-jobs

Get paginated print job history.

Query Parameters

Parameter	Type	Description
`per_page`	integer	Results per page (default: 15)
`status`	string	Filter by status (pending, processing, completed, failed, cancelled)

GET /api/print-jobs/{id}/download

Download the print file for a specific job.

Returns the file as a binary download with appropriate headers.

POST /api/print-jobs/{id}/status

Update the status of a print job.

Request Body

{
  "status": "processing",
  "error_message": "Optional error message if status is failed"
}

Valid status values:

processing - Job is being processed
completed / printed - Job completed successfully
failed - Job failed (include error_message)
cancelled - Job was cancelled

PUT /api/print-jobs/{id}/cancel

Cancel a pending or processing print job.

DELETE /api/print-jobs/{id}

Delete a print job and its associated file.

Error Codes

Status Code	Description
`200 OK`	Request successful
`201 Created`	Resource created successfully
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Invalid or missing authentication token
`403 Forbidden`	Insufficient permissions or quota exceeded
`404 Not Found`	Resource not found
`422 Unprocessable Entity`	Validation failed
`500 Internal Server Error`	Server error occurred

Rate Limiting

API requests are rate-limited based on your subscription plan:

Free Plan: 60 requests per minute
Professional Plan: 300 requests per minute
Enterprise Plan: 1000 requests per minute

Rate Limit Headers: Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to help you track your usage.