BIRCH Agent Document API — Agent Instructions

Use this API when an Iron Horse agent needs BIRCH workorder documents without driving the browser UI.

Production endpoint

POST https://birchbackend.ihrailsoftware.com/agent/workorder-documents

Current production status

The API is live behind the BIRCH backend ALB.

Verified behaviors:

• Existing BIRCH backend health/data route works:
  • GET https://birchbackend.ihrailsoftware.com/get_all_common_data → 200
• Document route without auth returns:
  • 401 Unauthorized
• Document route with valid bearer token returns the requested document:
  • ARR-500B returns plain text
  • BRC, invoice, BBOM, and work-order return PDFs
  • bill_to: all returns a zip when multiple files apply

Authentication

Every request must include:

Authorization: Bearer <BIRCH_AGENT_DOCUMENT_API_KEY>

Do not paste the token into chat, task logs, commits, or public docs.

The production token is stored in AWS Systems Manager Parameter Store as a SecureString:

/birch/prod/agent-document-api-key

If an agent has approved AWS access, retrieve it with:

aws ssm get-parameter \
  --region us-east-2 \
  --name /birch/prod/agent-document-api-key \
  --with-decryption \
  --query Parameter.Value \
  --output text

Use the value only in-process. Do not print it.

Example safe shell pattern:

BIRCH_DOC_TOKEN=$(aws ssm get-parameter \
  --region us-east-2 \
  --name /birch/prod/agent-document-api-key \
  --with-decryption \
  --query Parameter.Value \
  --output text)

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H "Authorization: Bearer ${BIRCH_DOC_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"arr-500b","bill_to":"owner"}' \
  -o 'BIRCH-WO_05926-arr-500b.txt'

unset BIRCH_DOC_TOKEN

Request body

Use either work_order or work_id.

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

Supported document_type values

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

For BRC/ARR/Invoice, billing maps to the same behavior as the BIRCH frontend:

combined    → frontend forWhom = 1
owner       → frontend forWhom = 2
lessee      → frontend forWhom = 3
third_party → frontend forWhom = 4

bill_to: all generates owner plus whichever billed parties are actually 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"

Common examples

ARR-500B text file

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H "Authorization: Bearer ${BIRCH_DOC_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"arr-500b","bill_to":"owner"}' \
  -o 'BIRCH-WO_05926-arr-500b.txt'

BRC PDF for owner

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H "Authorization: Bearer ${BIRCH_DOC_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"brc","bill_to":"owner"}' \
  -o 'WO_05926-brc-owner.pdf'

All applicable BRC files as zip

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H "Authorization: Bearer ${BIRCH_DOC_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"brc","bill_to":"all"}' \
  -o 'WO_05926-brc-all.zip'

Invoice PDF for third party

curl -fsS \
  -X POST 'https://birchbackend.ihrailsoftware.com/agent/workorder-documents' \
  -H "Authorization: Bearer ${BIRCH_DOC_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{"work_order":"WO_05926","document_type":"invoice","bill_to":"third_party"}' \
  -o 'WO_05926-invoice-third-party.pdf'

Python example

import os
import requests

url = "https://birchbackend.ihrailsoftware.com/agent/workorder-documents"
token = os.environ["BIRCH_DOC_TOKEN"]

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

response = requests.post(
    url,
    headers={"Authorization": f"Bearer {token}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()

with open("BIRCH-WO_05926-arr-500b.txt", "wb") as f:
    f.write(response.content)

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 → backend API key not configured
500 → PDFCrowd or unexpected generation failure

Operational deployment/runbook notes:

docs/birch-backend-production-deployment-runbook.md

Operational notes for agents

• Prefer this API over browser automation for document retrieval.
• Never store or log the bearer token.
• If you receive 401, your token is missing or wrong.
• If you receive 503, the backend container is missing BIRCH_AGENT_DOCUMENT_API_KEY.
• If you receive 404, verify the work order exists in BIRCH.
• For ARR-500B, save the response as .txt.
• For PDFs, save as .pdf.
• For bill_to: all, inspect Content-Type; it may be application/zip.

Deployment context, for troubleshooting only

Current live BIRCH backend ALB target:

i-00f8b6f49c1e4edac:5056

Current new container:

birch_backend_candidate
018772930825.dkr.ecr.us-east-2.amazonaws.com/birch_backend:latest
host port 5056 → container port 5055

Rollback container currently left running on the same instance:

birch_backend
mithuniht/birch_backend:latest
host port 5055 → container port 5055

Do not modify ALB targets, containers, security groups, or tokens unless explicitly performing an approved deployment/rollback task.