Public API & OpenAPI: A Contract, Not a Polite CSV Export

Some tenants will live inside ReVend OS all day. Others already have ERP, WMS, finance or BI systems that are not going to vanish because a nicer button arrived. The public API exists for those teams: structured access to operational records without copy-paste diplomacy.

What the API covers

The live /v1 surface includes assets, orders, evidence, documents, companies, contacts, company addresses, warehouses, catalog data, sellable assets, listings, auctions, events, webhooks and import jobs. It is not a demo endpoint wearing a blazer; the contract is generated, tested and exposed through OpenAPI.

OpenAPI

/api/v1/openapi.json publishes the API schema. Generated Postman, Bruno and TypeScript client artifacts are built from the same registry. That keeps docs, tests and the actual routes from drifting into three separate opinions.

Lifecycle guards

API writes use the same lifecycle ideas as the app: safe updates, status transitions, idempotency where required, soft-delete or archive behavior where history must remain. An API should not become the side door for doing things the UI correctly refuses.

Who should use it

Use the API when another system owns part of the workflow or needs reliable sync. Use CSV/imports when the need is one-off. Not every spreadsheet deserves OAuth and a swivel chair.