API Documentation

Read-only JSON API for querying entities and gaps. Authenticate with your API key via Bearer token.

Authentication

All requests require a Bearer token. Set PAM_API_KEY as an environment variable on your PAM instance. A settings-page key manager is planned for Q3 2026. 

curl -H "Authorization: Bearer YOUR_API_KEY" https://ws-pam.fly.dev/api/v1/entities

Endpoints

GET /api/v1/entities

List all entities in the workspace.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ws-pam.fly.dev/api/v1/entities

Response

[
  {
    "id": 1,
    "name": "Patrick Lord",
    "type": "person",
    "status": "active"
  },
  {
    "id": 2,
    "name": "123 Main St",
    "type": "property",
    "status": "active"
  }
]
GET /api/v1/entities/{id}

Get detail for a single entity including subtype, tags, and linked document count.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ws-pam.fly.dev/api/v1/entities/1

Response

{
  "id": 1,
  "name": "Patrick Lord",
  "type": "person",
  "subtype": "self",
  "status": "active",
  "tags": ["primary"],
  "doc_count": 14
}
GET /api/v1/entities/{id}/documents

List documents linked to an entity. Returns metadata only — document contents are never exposed.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ws-pam.fly.dev/api/v1/entities/1/documents

Response

[
  {
    "id": 42,
    "name": "2023_tax_return.pdf",
    "doc_type": "tax_form",
    "confidence": 0.94
  },
  {
    "id": 43,
    "name": "drivers_license_front.jpg",
    "doc_type": "license",
    "confidence": 0.88
  }
]
GET /api/v1/entities/{id}/gaps Primary endpoint

Return computed lifecycle gaps for an entity. Gaps reflect current document coverage against lifecycle rules — they are never stored and always fresh.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://ws-pam.fly.dev/api/v1/entities/1/gaps

Response

[
  {
    "gap_id": "person-1-tax_form",
    "doc_type": "tax_form",
    "status": "STALE",
    "rule_description": "Annual tax return — must be current year",
    "last_updated": "2024-04-15T00:00:00Z"
  },
  {
    "gap_id": "person-1-will",
    "doc_type": "will",
    "status": "MISSING",
    "rule_description": "Estate planning document required for adults",
    "last_updated": null
  },
  {
    "gap_id": "person-1-passport",
    "doc_type": "passport",
    "status": "URGENT",
    "rule_description": "Passport expiring within 6 months",
    "last_updated": "2019-03-01T00:00:00Z"
  }
]
Gap statuses: URGENT — document present but action required soon  ·  MISSING — no document found for this rule  ·  STALE — document present but outdated  ·  COMPLETE — rule satisfied

Notes

  • Documents stay in your storage — PAM reads and classifies metadata only.
  • Gaps are computed on demand from lifecycle rules × entity status × linked documents. They are never stored.
  • TOTEM credential delegation (Q3 2026) will introduce per-agent authorization for querying user gaps. Until then, the API key grants full read access.