API Reference

All routes are nested under /api/v1 except health and metrics endpoints.

Base URL

https://api-blocmarket.wyattau.com

Local development:

http://localhost:8090

Authentication

Protected endpoints require a JWT in the Authorization header:

Authorization: Bearer <jwt_token>

Obtain a token via POST /api/v1/auth/register or POST /api/v1/auth/login. The login response is flat: { "access_token", "refresh_token" }.

Enterprise API

Enterprise endpoints accept either a JWT or an API key:

Authorization: Bearer bmk_live_...

Enterprise OAuth clients exchange client credentials at POST /api/v1/enterprise/oauth/oauth/token.

Response Envelope

Most endpoints return { "data": { ... } }. Some endpoints return flat responses (noted in the tables below, e.g. login and bloc detail).

Error Format

Errors follow RFC 7807 Problem Details with content type application/problem+json:

{
  "type": "https://blocmarket.org/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "amount must be greater than zero"
}

Status	Meaning
400	Validation error
401	Authentication required or token expired
403	Insufficient permissions / CORS rejection
404	Resource not found
409	Conflict (duplicate)
429	Rate limit exceeded

Rate Limiting

Rate limiting is Redis-based with tiered limits:

Tier	Requests	Period	Applied To
Auth	15	60s	/auth/*, /enterprise/oauth/*
Public	100	60s	/search/*
User	1000	60s	All protected routes
Enterprise	Per-client	60s	Enterprise API key routes

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After (on 429). If Redis is unavailable, all requests are allowed (graceful degradation).

Pagination

Paginated endpoints accept page (default 1) and per_page or limit (default 20, max 100):

{ "data": [ ... ], "total": 42, "page": 1, "per_page": 20 }

Health & Monitoring

No authentication required. No rate limiting.

Method	Path	Description
GET	/	API status check
GET	/health	Health check (static)
GET	/health/db	Database connectivity (SELECT 1)
GET	/health/redis	Redis connectivity (TCP)
GET	/ready	Composite readiness (DB + Redis)
GET	/metrics	Prometheus metrics (text exposition)
WS	/ws	WebSocket notification stream

Authentication Endpoints

No JWT required. Rate limited: 15 req/min.

Method	Path	Description
POST	/api/v1/auth/register	Register new user
POST	/api/v1/auth/login	Login (flat { "access_token", "refresh_token" })
POST	/api/v1/auth/refresh	Refresh access token
POST	/api/v1/auth/forgot-password	Request password reset email
POST	/api/v1/auth/reset-password	Reset password with token
POST	/api/v1/auth/verify-email	Verify email with token

Users

JWT required.

Method	Path	Description
GET	/api/v1/users/profile	Get current user profile
PATCH	/api/v1/users/profile	Update profile
POST	/api/v1/users/password	Change password
POST	/api/v1/users/account/delete	Soft-delete account
POST	/api/v1/users/account/restore	Restore soft-deleted account
GET	/api/v1/users/me/export	Export all user data (GDPR)
GET	/api/v1/users/me/export/status	Check export status
DELETE	/api/v1/users/me	Permanent account deletion (GDPR)

Properties

JWT required. Rate limited: 1000 req/min.

Method	Path	Description
POST	/api/v1/properties	Create property
GET	/api/v1/properties/search	Search properties (paginated)
GET	/api/v1/properties/nearby	Find properties near coordinates
GET	/api/v1/properties/within-bounds	Find properties within bounding box
GET	/api/v1/properties/{id}	Get property by ID
PUT	/api/v1/properties/{id}	Update property
PUT	/api/v1/properties/{id}/status	Update property status
DELETE	/api/v1/properties/{id}	Delete property

Blocs

JWT required.

Method	Path	Description
GET	/api/v1/blocs	List blocs (paginated)
POST	/api/v1/blocs	Create bloc
GET	/api/v1/blocs/{id}	Get bloc by ID (flat BlocDto)
PUT	/api/v1/blocs/{id}	Update bloc
DELETE	/api/v1/blocs/{id}	Delete bloc
POST	/api/v1/blocs/{id}/properties	Add property to bloc
DELETE	/api/v1/blocs/{id}/properties/{property_id}	Remove property from bloc
POST	/api/v1/blocs/{id}/events	Submit bloc state event (flat BlocDto)
GET	/api/v1/blocs/{id}/transitions	Get transition history
POST	/api/v1/blocs/{id}/proposals	Create bloc proposal
POST	/api/v1/blocs/{id}/proposals/{proposal_id}/vote	Cast vote on proposal

Bids

JWT required.

Method	Path	Description
GET	/api/v1/bids	List bids (paginated)
POST	/api/v1/bids	Create bid
GET	/api/v1/bids/{id}	Get bid by ID
PUT	/api/v1/bids/{id}	Update bid
DELETE	/api/v1/bids/{id}	Delete bid
POST	/api/v1/bids/{id}/accept	Accept bid
POST	/api/v1/bids/{id}/reject	Reject bid

Transactions

JWT required.

Method	Path	Description
GET	/api/v1/transactions	List transactions (paginated)
POST	/api/v1/transactions	Create transaction
GET	/api/v1/transactions/{id}	Get transaction by ID
PUT	/api/v1/transactions/{id}	Update transaction fields
PUT	/api/v1/transactions/{id}/status	Update transaction status
POST	/api/v1/transactions/{id}/cancel	Cancel transaction
GET	/api/v1/transactions/{id}/milestones	Get transaction milestones
GET	/api/v1/transactions/bloc/{bloc_id}/active	Get active transaction for bloc

Payments

JWT required.

Method	Path	Description
GET	/api/v1/payments	List payments
POST	/api/v1/payments	Create payment
POST	/api/v1/payments/calculate-fee	Calculate platform fee
POST	/api/v1/payments/intent	Create Stripe payment intent
POST	/api/v1/payments/search	Search payments
GET	/api/v1/payments/{id}	Get payment by ID
PUT	/api/v1/payments/{id}	Update payment
DELETE	/api/v1/payments/{id}	Delete payment
PUT	/api/v1/payments/{id}/status	Update payment status
POST	/api/v1/payments/refund	Create refund
POST	/api/v1/payments/webhook	Stripe webhook handler
POST	/api/v1/payments/truelayer/create-intent	Create TrueLayer payment intent
POST	/api/v1/payments/truelayer/create-payment	Execute TrueLayer payment

Notifications

JWT required.

Method	Path	Description
POST	/api/v1/notifications	Create notification
GET	/api/v1/notifications	List notifications
GET	/api/v1/notifications/search	Search notifications
GET	/api/v1/notifications/{id}	Get notification by ID
PATCH	/api/v1/notifications/{id}/read	Mark as read
PATCH	/api/v1/notifications/read-all	Mark all as read
DELETE	/api/v1/notifications/{id}	Delete notification
GET	/api/v1/notifications/preferences	Get notification preferences
PATCH	/api/v1/notifications/preferences	Update preferences
POST	/api/v1/notifications/devices/register	Register push device
POST	/api/v1/notifications/devices/unregister	Unregister push device

Search

No JWT required. Rate limited: 100 req/min.

Method	Path	Description
GET	/api/v1/search/search	Global search

Expansion Products

All endpoints require JWT. Each product has full CRUD plus domain-specific operations:

Product	Base Path	Domain Operations
Site Assemblies	/api/v1/site-assemblies	Validate assembly, check contiguity
Rooftop Assemblies	/api/v1/rooftop-assemblies	Air rights valuation, PD rights assessment
Nutrient Credits	/api/v1/nutrient-credits	Calculate credit yield, transfer credits
SANOS (BNG)	/api/v1/sanos	Habitat quality, link to development, NE approval
Section 106	/api/v1/section-106	Match affordable housing sites, link luxury development
BESS Sites	/api/v1/bess-sites	Proximity search, substation validation, suitability
Edge Data Centers	/api/v1/edge-data-centers	Fiber availability, PUE estimate
Industrial Storage	/api/v1/industrial-storage	Revenue estimate, suitability
Telecom Leases	/api/v1/telecom-leases	Site/lease CRUD, line-of-sight analysis

Enterprise API

JWT or API key (Bearer bmk_live_...) required.

Method	Path	Description
GET / POST	/api/v1/enterprise/clients	List / create enterprise clients
GET / PUT / DELETE	/api/v1/enterprise/clients/{client_id}	Manage client
POST	/api/v1/enterprise/clients/{client_id}/regenerate-webhook-secret	Regenerate webhook secret
POST	/api/v1/enterprise/clients/{client_id}/test-webhook	Test webhook delivery
GET	/api/v1/enterprise/keys	List API keys
POST	/api/v1/enterprise/clients/{client_id}/keys	Create API key
DELETE	/api/v1/enterprise/keys/{key_id}	Delete API key
POST	/api/v1/enterprise/keys/{key_id}/revoke	Revoke API key
POST	/api/v1/enterprise/clients/{client_id}/revoke-tokens	Revoke OAuth tokens

DocuSign

JWT required.

Method	Path	Description
POST	/api/v1/docusign/send-envelope	Send DocuSign envelope
GET	/api/v1/docusign/envelope/{envelope_id}/status	Get envelope status
POST	/api/v1/docusign/envelope/{envelope_id}/void	Void envelope

Admin

JWT required. Admin role check in handlers.

Method	Path	Description
GET	/api/v1/admin/stats	System statistics
GET	/api/v1/admin/activity	Recent activity
PATCH	/api/v1/admin/users/role	Change user role

Swagger UI

Interactive API documentation is available at:

/api-docs/ui/

OpenAPI JSON spec:

/api-docs/openapi.json

Swagger UI is enabled by default in development. Disable in production with SWAGGER_UI_ENABLED=false.

WebSocket

Connect to /ws with a valid JWT for real-time updates:

ws://localhost:8090/ws?token=<jwt>

Events stream: bid updates, notification delivery, bloc state changes.

Security Headers

Applied to all responses:

Header	Value
Content-Security-Policy	default-src 'none'; connect-src 'self'; frame-ancestors 'none'
Strict-Transport-Security	max-age=63072000; includeSubDomains; preload
X-Frame-Options	DENY
X-Content-Type-Options	nosniff
X-XSS-Protection	1; mode=block
Referrer-Policy	strict-origin-when-cross-origin
Permissions-Policy	camera=(), microphone=(), geolocation=()
Cross-Origin-Embedder-Policy	require-corp
Cross-Origin-Opener-Policy	same-origin
Server	BlocMarket (version hidden)