API v1

Ontology

Semantic model, stable category codes, counterparties, and agent categorization rules.

BennyBooks uses a lightweight ontology so agents categorize by stable codes (5100) instead of ambiguous display names (Software vs Software & tools). Postgres remains the source of truth; JSON-LD / Turtle describe meaning.

Preferred agent flow

GET /categories → match description to counterparties/synonyms → POST /proposals/categorization with categoryCode + confidence + reason (+ evidence). Humans approve in Ledger → Approvals; the trail lives in Log (/log).

Public endpoints

Ontology (JSON-LD)

https://bennybooks.com/api/v1/ontology.jsonld

JSON-LD context

https://bennybooks.com/api/v1/ontology/context.jsonld

No authentication required. OpenAPI also lists get_ontology and get_ontology_context.

Core classes

Class	Purpose
Transaction	Money movement (negative amount = outflow)
Category	Chart-of-accounts slot — identify by code
Counterparty	Vendor/customer with aliases (seed list today; DB planned)
Receipt	Evidence document
Note	Free-text annotation
Proposal	Agent suggestion awaiting approval
Audit log entry	Agent write or human review event (Log UI)
Connector	Bank/payment data source

Default chart codes

Code	Name	Type	Synonyms
5100	Software & tools	expense	Software, SaaS, Subscriptions
5200	Office & rent	expense	Rent, Coworking, WeWork
5300	Cloud infrastructure	expense	Cloud, AWS, GCP, Azure
5000	Operating expenses	expense	Travel, Contractors, Professional services
4000	Revenue	revenue
4010	SaaS subscriptions	revenue

Seed counterparties

Vendor	Default code	Aliases
AWS	5300	Amazon Web Services, AMZN AWS
Figma	5100	FIGMA INC
Google Workspace	5100	Google Cloud
Stripe	4000	STRIPE PAYOUT
WeWork	5200

Propose with categoryCode

POST /api/v1/proposals/categorization

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "categoryCode": "5300",
  "confidence": 0.91,
  "reason": "Description matches counterparty AWS",
  "evidence": [
    { "type": "counterparty_match", "value": "aws" }
  ]
}

category (name) still works for compatibility. Prefer categoryCode. The API resolves codes to the canonical chart name stored on the transaction today.

Full reference: docs/ONTOLOGY.md. Source files: ontology/bennybooks.jsonld and ontology/bennybooks.ttl.