Skip to main content

Standalone BIRCH Document API

The BIRCH workorder document generator is now hosted separately from the BIRCH backend on the Iron Horse API server.

Production endpoint​

POST https://api.ihrailsoftware.com/api/birch/documents/agent/workorder-documents

Service host​

API server: iht-api.tail2162ca.ts.net
Service path: /home/ubuntu/birch-document-api
PM2 process: birch-document-api
Local bind: 127.0.0.1:3017
Public proxy: nginx on api.ihrailsoftware.com

Authentication​

Every request must include:

Authorization: Bearer <token>

The token must not be pasted into chat, source code, docs, task logs, or memory. Approved agents should load it from a local secret/env file only.

Current secure handoff file on the API server:

/home/ubuntu/agent-secrets/birch-document-api.env

That file contains:

BIRCH_DOCUMENT_API_BASE_URL
BIRCH_DOCUMENT_API_ENDPOINT
BIRCH_DOCUMENT_API_KEY

Request body​

Use either work_order or work_id.

{
  "work_order": "WO_05926",
  "document_type": "arr-500b",
  "bill_to": "owner"
}

Supported document types​

brc
arr-500b
invoice
bbom
work-order

Aliases accepted:

aar       → arr-500b
aar-500b  → arr-500b
bom       → bbom
workorder → work-order
wo        → work-order

Supported bill_to values​

owner
lessee
third_party
combined
all

Aliases accepted:

leasee      → lessee
3rd_party   → third_party
thirdparty  → third_party

bill_to: all generates owner plus whichever billed parties are present and returns a zip if multiple files are produced.

Response types​

Single BRC / invoice / BBOM / work-order:

Content-Type: application/pdf
Content-Disposition: attachment; filename="...pdf"

Single ARR-500B:

Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="BIRCH <railcar>.txt"

Multiple files:

Content-Type: application/zip
Content-Disposition: attachment; filename="workorder-<work_order>-documents.zip"

Example curl​

set -a
. /approved/secret/path/birch-document-api.env
set +a

curl -fsS \
  -X POST "$BIRCH_DOCUMENT_API_ENDPOINT" \
  -H "Authorization: Bearer ${BIRCH_DOCUMENT_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"arr-500b","bill_to":"owner"}' \
  -o 'BIRCH-WO_05926-arr-500b.txt'

Error codes​

400 → unsupported document type, unsupported bill_to, missing work order, or invoice PO validation failure
401 → missing/wrong bearer token
404 → work order not found
503 → API key not configured
500 → PDF generation or unexpected generation failure

Verification evidence​

Verified after deployment:

Local health: 200 { ok: true, service: birch-document-api, configured: true }
Public no-auth request: 401 application/json
Public ARR-500B request with auth: 200 text/plain; 4509 bytes; first record starts DIHS
Public BRC request with auth: 200 application/pdf; PDF magic %PDF; 22109 bytes
Unit tests: 9 passed, 0 failed

Implementation notes​

The standalone service was ported from the BIRCH backend document API implementation but no longer depends on the BIRCH backend deployment path. It reads the BIRCH database directly through Prisma and generates PDFs locally with Playwright Chromium instead of PDFCrowd.