Skip to main content

TVL Platform API Changelog

Summary​

This document tracks all changes to the TVL Platform API, including new endpoints, breaking changes, deprecations, and bug fixes.

Versioning Strategy​

Version Format​

TVL Platform API follows Semantic Versioning: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes (incompatible API changes)
  • MINOR: New functionality (backward-compatible)
  • PATCH: Bug fixes (backward-compatible)

API Version Header​

Accept: application/vnd.tvl.v1+json

Deprecation Policy​

  • Deprecated endpoints remain functional for 6 months minimum
  • Deprecation notices include removal date and migration path
  • Deprecated endpoints return Deprecation header: 
    Deprecation: date="2025-12-31"
    Sunset: date="2026-06-30"
    Link: <https://docs.tvl.com/api/migration-guide>; rel="deprecation"

Breaking vs. Non-Breaking Changes​

Breaking Changes (Require MAJOR version bump)​

  • Removing or renaming endpoints
  • Removing or renaming fields in responses
  • Changing field types
  • Adding required request parameters
  • Changing error response format
  • Changing authentication mechanism

Non-Breaking Changes (MINOR or PATCH version bump)​

  • Adding new endpoints
  • Adding optional request parameters
  • Adding new fields to responses
  • Fixing bugs without changing interface
  • Performance improvements
  • Security patches

Version History​

v1.0.0 - 2025-10-24 (Initial Release)​

New Features​

Authentication & Identity

  • POST /auth/login - Google OIDC authentication
  • POST /auth/logout - Logout and session termination
  • GET /users/me - Get current user profile
  • PATCH /users/me - Update user profile
  • POST /organizations - Create organization
  • GET /organizations/{orgId} - Get organization details
  • POST /organizations/{orgId}/members - Add team member
  • DELETE /organizations/{orgId}/members/{userId} - Remove member
  • POST /organizations/{orgId}/invitations - Send invitation
  • GET /users/{userId}/permissions - Get user permissions

Supply Management

  • POST /properties - Create property
  • GET /properties - List properties with filtering
  • GET /properties/{propertyId} - Get property details
  • PATCH /properties/{propertyId} - Update property
  • DELETE /properties/{propertyId} - Soft delete property
  • POST /properties/{propertyId}/units - Create unit
  • GET /units/{unitId} - Get unit details
  • PATCH /units/{unitId} - Update unit
  • POST /properties/{propertyId}/media - Upload property images
  • DELETE /media/{mediaId} - Delete media item

Availability Management

  • GET /units/{unitId}/calendar - Get availability calendar
  • GET /units/{unitId}/availability - Check availability for date range
  • POST /units/{unitId}/blocks - Create availability block
  • PATCH /blocks/{blockId} - Update block
  • DELETE /blocks/{blockId} - Remove block

Pricing

  • GET /units/{unitId}/pricing - Get pricing for date range
  • POST /quotes - Generate quote
  • GET /quotes/{quoteId} - Get quote details
  • POST /price-rules - Create pricing rule
  • GET /price-rules - List pricing rules
  • PATCH /price-rules/{ruleId} - Update pricing rule
  • DELETE /price-rules/{ruleId} - Delete pricing rule

Bookings

  • POST /quotes/{quoteId}/hold - Convert quote to hold
  • POST /holds/{holdId}/confirm - Convert hold to booking
  • GET /bookings - List bookings with filtering
  • GET /bookings/{bookingId} - Get booking details
  • POST /bookings/{bookingId}/cancel - Cancel booking
  • PATCH /bookings/{bookingId} - Update booking

Payments

  • POST /payment-intents - Create payment intent
  • POST /payments/{paymentId}/capture - Capture payment
  • POST /refunds - Create refund
  • GET /payments/{paymentId} - Get payment details
  • GET /transactions - List transactions

Channels & Distribution

  • POST /channels - Register channel
  • GET /channels - List channels
  • POST /channels/{channelId}/listings - Create listing
  • GET /listings/{listingId} - Get listing details
  • POST /channels/{channelId}/sync - Trigger manual sync
  • GET /sync-logs - Get sync history

Connectors

  • POST /connectors/hostaway/webhook - Receive Hostaway webhook
  • POST /connectors/hostaway/sync - Trigger manual sync
  • GET /connectors/hostaway/mappings - Get field mappings
  • PUT /connectors/hostaway/mappings - Update field mappings

Webhooks (Inbound)

  • POST /webhooks/stripe - Stripe webhook handler
  • POST /webhooks/hostaway - Hostaway webhook handler

System

  • GET /health - Health check endpoint
  • GET /metrics - Prometheus metrics

API Features​

  • JWT Bearer authentication for all endpoints
  • Cursor-based pagination for list endpoints
  • Idempotency keys for write operations
  • Rate limiting: 1000 req/min per tenant
  • ETag support for optimistic locking
  • Structured error responses with codes
  • Request ID tracking for debugging
  • CORS support for web clients

Data Models​

  • All timestamps in ISO 8601 format with timezone
  • Currency amounts in cents (integers)
  • UUIDs for all resource identifiers
  • Soft deletes with deleted_at timestamp

Upcoming Changes (Planned)​

v1.1.0 - Q1 2026 (Planned)​

New Features

  • POST /reports/occupancy - Generate occupancy report
  • POST /reports/revenue - Generate revenue report
  • GET /analytics/dashboard - Dashboard metrics API
  • POST /units/{unitId}/ical-import - Import iCal feed
  • GET /units/{unitId}/ical-export - Export iCal feed
  • Batch operations for availability blocks
  • Webhook subscriptions for external consumers

Enhancements

  • Advanced filtering for bookings (by date range, status, channel)
  • Bulk unit updates
  • Property duplication API
  • Enhanced search with full-text queries

v2.0.0 - Q3 2026 (Future)​

Breaking Changes (Tentative)

  • Migrate to GraphQL API (REST API v1 remains for 12 months)
  • Restructure error response format for consistency
  • Remove deprecated type field from properties (replaced with property_type)

Deprecation Notices​

Currently Deprecated​

No endpoints currently deprecated.

Deprecation Schedule​

Future deprecations will be listed here with removal dates.

Migration Guides​

From v0 (Beta) to v1.0.0​

Breaking Changes

  1. Authentication: Changed from API keys to JWT tokens

    • Before: Authorization: ApiKey <key>
    • After: Authorization: Bearer <jwt>
    • Action: Update auth header in all API calls

  2. Date Format: Standardized to ISO 8601

    • Before: "2025-10-24" (date only)
    • After: "2025-10-24T00:00:00Z" (with timezone)
    • Action: Update date parsing to handle full timestamps

  3. Pagination: Changed from offset to cursor

    • Before: ?page=2&limit=20
    • After: ?cursor=abc123&limit=20
    • Action: Update pagination logic to use cursors

  4. Error Format: Structured error responses

    • Before: {"error": "Not found"}
    • After: {"error": {"code": "NOT_FOUND", "message": "Resource not found", "details": {}}}
    • Action: Update error handling to parse new format

Validation & Alternatives​

API Design Decisions​

✅ Agree: RESTful API with JSON for MVP

  • Alternative: GraphQL
  • Trade-off: REST is simpler for initial clients; GraphQL adds flexibility but complexity

✅ Agree: Cursor-based pagination

  • Alternative: Offset-based pagination
  • Trade-off: Cursors handle inserts/deletes during pagination better

✅ Agree: Idempotency keys required for write operations

  • Alternative: No idempotency guarantees
  • Trade-off: Adds client complexity but prevents duplicate operations

⚠️ Consider: API versioning via header vs. URL path

  • Current: Header-based (Accept: application/vnd.tvl.v1+json)
  • Alternative: URL path (/v1/properties)
  • Recommendation: Header-based is cleaner but requires client support; URL path is more visible

Known Gaps & Assumptions​

Assumptions​

  1. JWT tokens expire after 24 hours (refresh tokens not yet implemented)
  2. API clients handle cursor-based pagination
  3. Idempotency keys are UUID v4 format
  4. All API consumers accept JSON responses

Gaps​

  1. No GraphQL API (future consideration)
  2. No batch operations (coming in v1.1.0)
  3. No webhook subscriptions for external consumers (coming in v1.1.0)
  4. No API rate limit customization per tenant (fixed at 1000 req/min)

Sources​

  • meta/research-log.md
  • docs/02-domains/*/spec.md