SapienStream

Documents API

Comprehensive document and compliance management for industrial machinery. Handle technical documentation, safety certificates, calibration records, and regulatory compliance artifacts with version control and approval workflows.

Overview

Document Types

  • • Manual: Operation and maintenance manuals
  • • Wiring: Electrical diagrams and schematics
  • • Safety: Safety procedures and risk assessments
  • • Validation: Validation protocols and test results
  • • P&ID: Process & Instrumentation Diagrams
  • • Calibration: Calibration certificates
  • • Certificate: Compliance certificates (CE, UL)
  • • Procedure: Standard operating procedures

Features

  • • Version control and history tracking
  • • Approval workflow management
  • • Document expiration monitoring
  • • File integrity verification (SHA256)
  • • Access control and public visibility
  • • Metadata search and categorization
  • • Review scheduling and notifications
  • • Compliance status tracking

Document Data Model

Document Properties
Complete document metadata with approval workflow and compliance tracking
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "title": "Reactor Safety Manual Rev 3.2",
  "document_kind": "manual",
  "uri": "s3://documents/reactor-safety-manual-v3.2.pdf",
  "filename": "reactor-safety-manual-v3.2.pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "sha256_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "version": "3.2",
  "is_current": true,
  "description": "Updated safety procedures for reactor operations including new emergency protocols",
  "tags": ["safety", "reactor", "emergency", "procedures"],
  "approval_status": "approved",
  "approved_by": "safety_manager",
  "approved_at": "2024-08-20T09:00:00Z",
  "expires_at": "2025-08-20T23:59:59Z",
  "review_due_at": "2025-02-20T00:00:00Z",
  "is_public": false,
  "access_level": "restricted",
  "created_at": "2024-08-15T14:30:00Z",
  "updated_at": "2024-08-20T09:00:00Z",
  "created_by": "engineer1",
  "updated_by": "safety_manager"
}

Document Categories

Technical
  • • Operation Manuals
  • • Wiring Diagrams
  • • P&ID Drawings
  • • Procedures
Safety & Compliance
  • • Safety Procedures
  • • Risk Assessments
  • • Compliance Certificates
  • • Validation Reports
Quality
  • • Calibration Certificates
  • • Test Results
  • • Validation Protocols
  • • Quality Records

Approval Workflow

DRAFT

Document in preparation, not yet submitted for review.

PENDING

Submitted for approval, awaiting review by authorized personnel.

APPROVED

Document approved and authorized for operational use.

REJECTED

Document rejected, requires revision before resubmission.

API Endpoints

GET/documents/{machine_id}Auth Required
List Documents
Get all documents for a specific machine with filtering, search, and approval status options.

Parameters

machine_idstringRequired

Unique identifier of the machine

current_onlyboolean

Show only current document versions (default: true)

document_kindstring

Filter by document type (manual, wiring, safety, etc.)

approval_statusstring

Filter by approval status (draft, pending, approved, rejected)

expired_onlyboolean

Show only expired documents (default: false)

searchstring

Search in titles, descriptions, and filenames

limitinteger

Maximum results (max: 100, default: 50)

offsetinteger

Number of results to skip (default: 0)

Response

Responsejson
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "machine_id": "machine_001",
    "title": "Reactor Safety Manual Rev 3.2",
    "document_kind": "manual",
    "filename": "reactor-safety-manual-v3.2.pdf",
    "file_size": 2048576,
    "version": "3.2",
    "approval_status": "approved",
    "expires_at": "2025-08-20T23:59:59Z",
    "is_current": true,
    "is_public": false,
    "created_at": "2024-08-15T14:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "machine_id": "machine_001",
    "title": "Emergency Shutdown Procedure",
    "document_kind": "safety",
    "filename": "emergency-shutdown-v2.1.pdf",
    "file_size": 1024768,
    "version": "2.1",
    "approval_status": "approved",
    "expires_at": null,
    "is_current": true,
    "is_public": false,
    "created_at": "2024-07-10T08:15:00Z"
  }
]

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/documents/{machine_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/documents/{machine_id}/{document_id}Auth Required
Get Document Details
Retrieve comprehensive information about a specific document including metadata, approval details, and file information.

Parameters

machine_idstringRequired

Unique identifier of the machine

document_idstringRequired

UUID of the document to retrieve

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "title": "Reactor Safety Manual Rev 3.2",
  "document_kind": "manual",
  "uri": "s3://documents/reactor-safety-manual-v3.2.pdf",
  "filename": "reactor-safety-manual-v3.2.pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "sha256_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "version": "3.2",
  "is_current": true,
  "description": "Updated safety procedures for reactor operations including new emergency protocols",
  "tags": ["safety", "reactor", "emergency", "procedures"],
  "approval_status": "approved",
  "approved_by": "safety_manager",
  "approved_at": "2024-08-20T09:00:00Z",
  "expires_at": "2025-08-20T23:59:59Z",
  "review_due_at": "2025-02-20T00:00:00Z",
  "is_public": false,
  "access_level": "restricted",
  "created_at": "2024-08-15T14:30:00Z",
  "updated_at": "2024-08-20T09:00:00Z",
  "created_by": "engineer1",
  "updated_by": "safety_manager"
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/documents/{machine_id}/{document_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/documents/{machine_id}Auth Required
Create Document
Create a new document record for a machine. This creates the metadata entry for a file already uploaded to storage.

Parameters

machine_idstringRequired

Unique identifier of the machine

created_bystringRequired

Username of the creator (query parameter)

Request Body

Requestjson
{
  "title": "Reactor Safety Manual Rev 3.2",
  "document_kind": "manual",
  "uri": "s3://documents/reactor-safety-manual-v3.2.pdf",
  "filename": "reactor-safety-manual-v3.2.pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "sha256_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "version": "3.2",
  "description": "Updated safety procedures for reactor operations including new emergency protocols",
  "tags": ["safety", "reactor", "emergency", "procedures"],
  "approval_status": "draft",
  "expires_at": "2025-08-20T23:59:59Z",
  "review_due_at": "2025-02-20T00:00:00Z",
  "is_public": false,
  "access_level": "restricted"
}

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "title": "Reactor Safety Manual Rev 3.2",
  "document_kind": "manual",
  "uri": "s3://documents/reactor-safety-manual-v3.2.pdf",
  "filename": "reactor-safety-manual-v3.2.pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "sha256_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "version": "3.2",
  "is_current": true,
  "description": "Updated safety procedures for reactor operations including new emergency protocols",
  "tags": ["safety", "reactor", "emergency", "procedures"],
  "approval_status": "draft",
  "approved_by": null,
  "approved_at": null,
  "expires_at": "2025-08-20T23:59:59Z",
  "review_due_at": "2025-02-20T00:00:00Z",
  "is_public": false,
  "access_level": "restricted",
  "created_at": "2024-08-26T12:00:00Z",
  "updated_at": "2024-08-26T12:00:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/documents/{machine_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
PUT/documents/{machine_id}/{document_id}Auth Required
Update Document
Modify document metadata including approval status, expiration dates, and descriptive information.

Parameters

machine_idstringRequired

Unique identifier of the machine

document_idstringRequired

UUID of the document to update

updated_bystringRequired

Username of the updater (query parameter)

Request Body

Requestjson
{
  "title": "Reactor Safety Manual Rev 3.3",
  "version": "3.3",
  "description": "Updated safety procedures with new emergency protocols and revised shutdown sequence",
  "tags": ["safety", "reactor", "emergency", "procedures", "shutdown"],
  "approval_status": "approved",
  "expires_at": "2025-12-31T23:59:59Z",
  "review_due_at": "2025-06-30T00:00:00Z",
  "is_current": true
}

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "title": "Reactor Safety Manual Rev 3.3",
  "document_kind": "manual",
  "uri": "s3://documents/reactor-safety-manual-v3.2.pdf",
  "filename": "reactor-safety-manual-v3.2.pdf",
  "file_size": 2048576,
  "mime_type": "application/pdf",
  "sha256_hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "version": "3.3",
  "is_current": true,
  "description": "Updated safety procedures with new emergency protocols and revised shutdown sequence",
  "tags": ["safety", "reactor", "emergency", "procedures", "shutdown"],
  "approval_status": "approved",
  "approved_by": null,
  "approved_at": null,
  "expires_at": "2025-12-31T23:59:59Z",
  "review_due_at": "2025-06-30T00:00:00Z",
  "is_public": false,
  "access_level": "restricted",
  "created_at": "2024-08-15T14:30:00Z",
  "updated_at": "2024-08-26T12:30:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Try it out

cURLbash
curl -X PUT "https://sapienstream.com/api/documents/{machine_id}/{document_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
DELETE/documents/{machine_id}/{document_id}Auth Required
Delete Document
Permanently remove a document record. Note: This only removes the metadata; file deletion is handled separately.

Parameters

machine_idstringRequired

Unique identifier of the machine

document_idstringRequired

UUID of the document to delete

Response

Responsejson
204 No Content

Try it out

cURLbash
curl -X DELETE "https://sapienstream.com/api/documents/{machine_id}/{document_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/documents/{machine_id}/statsAuth Required
Document Statistics
Get aggregated statistics about documents for a specific machine including counts by type and approval status.

Parameters

machine_idstringRequired

Unique identifier of the machine

Response

Responsejson
{
  "machine_id": "machine_001",
  "total_documents": 42,
  "current_documents": 38,
  "old_versions": 4,
  "expired_documents": 2,
  "total_file_size_bytes": 157286400,
  "by_document_kind": {
    "manual": 8,
    "wiring": 12,
    "safety": 6,
    "validation": 4,
    "p_and_id": 3,
    "calibration": 5,
    "certificate": 3,
    "procedure": 1
  },
  "by_approval_status": {
    "approved": 35,
    "pending": 4,
    "draft": 2,
    "rejected": 1
  }
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/documents/{machine_id}/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Future Endpoints

Planned File Operations
Direct file upload and download capabilities (implementation pending)

POST /documents/{machine_id}/upload

Direct file upload to secure storage with automatic metadata extraction and integrity verification.

GET /documents/{machine_id}/{document_id}/download

Secure document download with access control and audit logging.

Common Use Cases

Real-world Applications
Examples of document management in industrial environments

Compliance Management

Track safety certificates, calibration records, and regulatory documentation with automatic expiration alerts.

Certificates → Expiration Monitoring → Renewal Alerts

Version Control

Maintain current and historical versions of technical documentation with approval workflows.

Manual v1.0 → v2.0 → v3.0 (current)

Safety Documentation

Centralize safety procedures, risk assessments, and emergency protocols with controlled access.

Risk Assessment → Safety Procedure → Emergency Protocol

Technical Drawing Management

Store and manage wiring diagrams, P&IDs, and technical schematics with version tracking.

P&ID → Wiring Diagram → As-Built Documentation

Error Responses

Common Error Codes

400 Bad Request

{
  "detail": "Invalid document_kind: 'INVALID' not in allowed values"
}

404 Not Found

{
  "detail": "Document with ID '550e8400-e29b-41d4-a716-446655440999' not found on machine 'machine_001'"
}

422 Validation Error

{
  "detail": "File size must be greater than 0 bytes"
}

501 Not Implemented

{
  "detail": "Document upload - implementation pending"
}