API Reference

Complete interactive API documentation with request/response examples and the ability to test endpoints directly from your browser.

Interactive API Documentation

We provide a complete OpenAPI/Swagger UI documentation that allows you to explore all endpoints, view request/response schemas, and test API calls directly.

View Interactive API Docs

Access the full Swagger UI documentation with all endpoints, schemas, and the ability to make test requests.

Quick Reference

Base URL

https://xyz.convex.site/api/v1

Authentication

API Key (Header):

x-app-key: YOUR_API_KEY

OAuth 2.0 (Header):

Authorization: Bearer YOUR_TOKEN

Endpoint Categories

📋Task Manager

POST/task-manager/requests
GET/task-manager/requests
GET/task-manager/requests/:id
PUT/task-manager/requests/:id
POST/task-manager/requests/:id/assign

🏨Property Management

POST/property-management/housekeeping/reports
GET/property-management/housekeeping/reports
GET/property-management/rooms
PUT/property-management/rooms/:id

🔔Oracle Webhooks

POST/webhooks/oracle/reservations
POST/webhooks/oracle/rooms
POST/webhooks/oracle/housekeeping
POST/webhooks/oracle/guest-requests

💚Health & Status

GET/health

Response Format

All API responses follow a consistent format:

Success Response:

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response:

{
  "success": false,
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Missing required field: categoryId",
    "instance": "/api/v1/task-manager/requests",
    "timestamp": "2026-02-16T10:30:00Z",
    "traceId": "abc123xyz",
    "errors": [
      {
        "field": "categoryId",
        "message": "This field is required"
      }
    ]
  }
}

Rate Limiting

All endpoints are rate limited. Check the following headers in responses:

X-RateLimit-Limit: 100        # Total requests per minute
X-RateLimit-Remaining: 95      # Remaining requests
X-RateLimit-Reset: 1640995200  # Unix timestamp when limit resets