prose-contracts/stirling-pdf-agent-access.prose.md

kind, name, version, description, author

kind	name	version	description	author
function	stirling-pdf-agent-access	1.0.0	Agent API access pattern for Stirling-PDF. All Syslog agents (Hermes, pi) use the global API key for programmatic PDF operations. No user login, no OAuth — just the X-API-Key header. Designed for automated document processing workflows.	Abiba (pi agent)

Stirling-PDF Agent Access Contract

Architecture

Agent (Hermes/pi) ──curl + X-API-Key──► Stirling-PDF (:8989) ──► /configs, /logs
                                              │
                                    docker-vm (192.168.68.7)

Connection Details

Field	Value
Base URL	http://192.168.68.7:8989
Auth Method	API Key (header)
Header Name	X-API-Key
API Key	adefaef837314afc37803747049c2e73f456da97699ff1b02b391347c4a3cb88
Key Source	SECURITY_CUSTOMGLOBALAPIKEY in /opt/home_stack/docker-compose.yml
Swagger	http://192.168.68.7:8989/swagger-ui.html
Health	http://192.168.68.7:8989/api/v1/info/status

Agent Integration

Hermes Agents

The shared skill stirling-pdf-api is available in RA-H OS. Hermes agents load it from the knowledge graph and use the documented curl patterns.

pi (Abiba)

Direct bash invocations:

curl -X POST "http://192.168.68.7:8989/api/v1/split-pdf" \
  -H "X-API-Key: adefaef837314afc37803747049c2e73f456da97699ff1b02b391347c4a3cb88" \
  -F "fileInput=@/path/to/file.pdf" \
  -F "pageNumbers=1,2,3" \
  -o /tmp/output.zip

Supported Operations

Operation	Endpoint	Input	Output
Split PDF	POST /api/v1/split-pdf	PDF + page numbers	ZIP of PDFs
Merge PDFs	POST /api/v1/merge-pdfs	2+ PDFs	Single PDF
PDF → Images	POST /api/v1/convert/pdf-to-img	PDF + format	ZIP of images
Images → PDF	POST /api/v1/convert/img-to-pdf	1+ images	Single PDF
OCR PDF	POST /api/v1/ocr-pdf	Scanned PDF	Searchable PDF
Compress PDF	POST /api/v1/compress-pdf	PDF + level	Smaller PDF
Remove Pages	POST /api/v1/remove-pages	PDF + page list	Trimmed PDF
Rotate PDF	POST /api/v1/rotate-pdf	PDF + angle	Rotated PDF
Add Password	POST /api/v1/add-password	PDF + password	Encrypted PDF
Remove Password	POST /api/v1/remove-password	PDF + password	Unlocked PDF
Add Watermark	POST /api/v1/add-watermark	PDF + text	Watermarked PDF
PDF Info	POST /api/v1/pdf-info	PDF	JSON metadata

Security

• API key stored ONLY in docker-compose (survives upgrades)
• API key bypasses user authentication — agents don't need user accounts
• docker-vm is internal (192.168.68.7), not exposed to internet directly
• Public access via NetBird nginx: https://pdf.sysloggh.net (user login only, agents use internal IP)

Related Contracts

• infrastructure-control.prose.md — docker-vm ecosystem, Stirling-PDF service details
• hermes-config-template.prose.md — agent configuration template
• Shared skill: stirling-pdf-api — API usage patterns and curl examples for agents