---
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