82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
---
|
|
kind: function
|
|
name: stirling-pdf-agent-access
|
|
version: 1.0.0
|
|
description: >
|
|
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.
|
|
author: 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:
|
|
```bash
|
|
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
|