navidocs/API_ENDPOINTS.md

NaviDocs API Endpoints Documentation

Version: 1.0.0 Date: 2025-11-14 Base URL: https://api.example.com (production) Total Endpoints: 32 Authentication: JWT Bearer Token

---

Table of Contents

1. Authentication
2. Inventory Endpoints (5)
3. Maintenance Endpoints (5)
4. Camera Endpoints (7)
5. Contacts Endpoints (7)
6. Expenses Endpoints (8)
7. Response Codes
8. Error Handling
9. Rate Limiting

---

Authentication

All endpoints (except health check) require JWT Bearer token authentication.

Request Header

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Example

curl -X GET https://api.example.com/api/inventory/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Health Check (No Auth Required)

GET /health

---

Inventory Endpoints (5)

Manage equipment, tools, and inventory items for boats.

1. Create Inventory Item

Endpoint: POST /api/inventory

Authentication: Required

Description: Create a new inventory item with optional photo uploads.

Request Parameters:

• boat_id (number, required): Boat ID
• name (string, required): Equipment name
• category (string, optional): Category (e.g., "Engine", "Safety", "Navigation")
• purchase_date (string, optional): Purchase date (YYYY-MM-DD format)
• purchase_price (number, optional): Purchase price in EUR
• depreciation_rate (number, optional): Annual depreciation rate (default: 0.1 for 10%)
• notes (string, optional): Additional notes

Request Body Schema:

{
  "boat_id": 123,
  "name": "Marine Engine Oil 5L",
  "category": "Maintenance Supplies",
  "purchase_date": "2025-01-15",
  "purchase_price": 45.50,
  "depreciation_rate": 0.10,
  "notes": "Synthetic blend, replace annually"
}

Response Schema (200 Created):

{
  "id": 1,
  "boat_id": 123,
  "name": "Marine Engine Oil 5L",
  "category": "Maintenance Supplies",
  "purchase_date": "2025-01-15",
  "purchase_price": 45.50,
  "current_value": 45.50,
  "depreciation_rate": 0.10,
  "photo_urls": ["/uploads/inventory/photo1.jpg"],
  "notes": "Synthetic blend, replace annually",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/inventory \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "boat_id": 123,
    "name": "Marine Engine Oil 5L",
    "category": "Maintenance Supplies",
    "purchase_date": "2025-01-15",
    "purchase_price": 45.50,
    "depreciation_rate": 0.10,
    "notes": "Synthetic blend"
  }'

---

2. List Inventory Items

Endpoint: GET /api/inventory/:boatId

Authentication: Required

Description: Get all inventory items for a specific boat.

URL Parameters:

• boatId (number, required): Boat ID

Query Parameters:

• category (string, optional): Filter by category
• sort_by (string, optional): Sort field (default: "category")
• order (string, optional): Sort order (asc/desc, default: asc)

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "name": "Marine Engine Oil 5L",
    "category": "Maintenance Supplies",
    "purchase_date": "2025-01-15",
    "purchase_price": 45.50,
    "current_value": 40.95,
    "depreciation_rate": 0.10,
    "photo_urls": [],
    "notes": "Synthetic blend",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/inventory/123?category=Engine" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

3. Get Inventory Item Details

Endpoint: GET /api/inventory/:boatId/:itemId

Authentication: Required

Description: Get details of a specific inventory item.

URL Parameters:

• boatId (number, required): Boat ID
• itemId (number, required): Inventory item ID

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "name": "Marine Engine Oil 5L",
  "category": "Maintenance Supplies",
  "purchase_date": "2025-01-15",
  "purchase_price": 45.50,
  "current_value": 40.95,
  "depreciation_rate": 0.10,
  "photo_urls": ["/uploads/inventory/photo1.jpg"],
  "notes": "Synthetic blend, replace annually",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X GET https://api.example.com/api/inventory/123/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

4. Update Inventory Item

Endpoint: PUT /api/inventory/:id

Authentication: Required

Description: Update an inventory item.

URL Parameters:

• id (number, required): Inventory item ID

Request Body Schema:

{
  "name": "Updated Equipment Name",
  "category": "Navigation",
  "purchase_price": 50.00,
  "current_value": 50.00,
  "depreciation_rate": 0.15,
  "notes": "Updated notes"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "name": "Updated Equipment Name",
  "category": "Navigation",
  "purchase_date": "2025-01-15",
  "purchase_price": 50.00,
  "current_value": 50.00,
  "depreciation_rate": 0.15,
  "photo_urls": [],
  "notes": "Updated notes",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:45:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/inventory/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Equipment Name",
    "category": "Navigation"
  }'

---

5. Delete Inventory Item

Endpoint: DELETE /api/inventory/:id

Authentication: Required

Description: Delete an inventory item.

URL Parameters:

• id (number, required): Inventory item ID

Response Schema (200 OK):

{
  "success": true,
  "message": "Inventory item deleted successfully"
}

Example cURL:

curl -X DELETE https://api.example.com/api/inventory/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Maintenance Endpoints (5)

Track boat maintenance records and service history.

1. Create Maintenance Record

Endpoint: POST /api/maintenance

Authentication: Required

Description: Create a new maintenance record for a boat.

Request Body Schema:

{
  "boat_id": 123,
  "service_type": "Engine Oil Change",
  "date": "2025-01-15",
  "provider": "Marina Mechanics Inc",
  "cost": 150.00,
  "next_due_date": "2025-04-15",
  "notes": "Synthetic oil, 5000 mile service"
}

Response Schema (201 Created):

{
  "id": 1,
  "boat_id": 123,
  "service_type": "Engine Oil Change",
  "date": "2025-01-15",
  "provider": "Marina Mechanics Inc",
  "cost": 150.00,
  "next_due_date": "2025-04-15",
  "notes": "Synthetic oil, 5000 mile service",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/maintenance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "boat_id": 123,
    "service_type": "Engine Oil Change",
    "date": "2025-01-15",
    "provider": "Marina Mechanics Inc",
    "cost": 150.00,
    "next_due_date": "2025-04-15",
    "notes": "Synthetic oil, 5000 mile service"
  }'

---

2. List Maintenance Records

Endpoint: GET /api/maintenance/:boatId

Authentication: Required

Description: Get all maintenance records for a boat.

URL Parameters:

• boatId (number, required): Boat ID

Query Parameters:

• status (string, optional): Filter by status (completed/pending)
• start_date (string, optional): Filter from date (YYYY-MM-DD)
• end_date (string, optional): Filter to date (YYYY-MM-DD)

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "service_type": "Engine Oil Change",
    "date": "2025-01-15",
    "provider": "Marina Mechanics Inc",
    "cost": 150.00,
    "next_due_date": "2025-04-15",
    "notes": "Synthetic oil, 5000 mile service",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/maintenance/123?status=pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

3. Get Upcoming Maintenance

Endpoint: GET /api/maintenance/:boatId/upcoming

Authentication: Required

Description: Get upcoming maintenance records (next_due_date in future).

URL Parameters:

• boatId (number, required): Boat ID

Query Parameters:

• days_ahead (number, optional): Look ahead days (default: 90)

Response Schema (200 OK):

[
  {
    "id": 2,
    "boat_id": 123,
    "service_type": "Hull Inspection",
    "date": null,
    "provider": "Boat Care Specialists",
    "cost": 200.00,
    "next_due_date": "2025-04-30",
    "notes": "Annual hull inspection",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/maintenance/123/upcoming?days_ahead=180" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

4. Update Maintenance Record

Endpoint: PUT /api/maintenance/:id

Authentication: Required

Description: Update a maintenance record.

URL Parameters:

• id (number, required): Maintenance record ID

Request Body Schema:

{
  "service_type": "Engine Oil Change (Complete)",
  "date": "2025-01-16",
  "cost": 160.00,
  "next_due_date": "2025-04-16"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "service_type": "Engine Oil Change (Complete)",
  "date": "2025-01-16",
  "provider": "Marina Mechanics Inc",
  "cost": 160.00,
  "next_due_date": "2025-04-16",
  "notes": "Synthetic oil, 5000 mile service",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:45:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/maintenance/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cost": 160.00,
    "next_due_date": "2025-04-16"
  }'

---

5. Delete Maintenance Record

Endpoint: DELETE /api/maintenance/:id

Authentication: Required

Description: Delete a maintenance record.

URL Parameters:

• id (number, required): Maintenance record ID

Response Schema (200 OK):

{
  "success": true,
  "message": "Maintenance record deleted successfully"
}

Example cURL:

curl -X DELETE https://api.example.com/api/maintenance/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Camera Endpoints (7)

Manage boat security cameras with Home Assistant RTSP/ONVIF integration.

1. Register Camera

Endpoint: POST /api/cameras

Authentication: Required

Description: Register a new camera feed for a boat.

Request Body Schema:

{
  "boat_id": 123,
  "camera_name": "Front Deck Camera",
  "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1"
}

Response Schema (201 Created):

{
  "id": 1,
  "boat_id": 123,
  "camera_name": "Front Deck Camera",
  "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1",
  "last_snapshot_url": null,
  "webhook_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/cameras \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "boat_id": 123,
    "camera_name": "Front Deck Camera",
    "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1"
  }'

---

2. List Cameras by Boat

Endpoint: GET /api/cameras/:boatId

Authentication: Required

Description: Get all cameras for a boat.

URL Parameters:

• boatId (number, required): Boat ID

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "camera_name": "Front Deck Camera",
    "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1",
    "last_snapshot_url": "https://s3.example.com/snapshots/camera-1-latest.jpg",
    "webhook_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET https://api.example.com/api/cameras/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

3. Get Camera Details

Endpoint: GET /api/cameras/:id

Authentication: Required

Description: Get details of a specific camera.

URL Parameters:

• id (number, required): Camera ID

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "camera_name": "Front Deck Camera",
  "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1",
  "last_snapshot_url": "https://s3.example.com/snapshots/camera-1-latest.jpg",
  "webhook_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X GET https://api.example.com/api/cameras/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

4. Update Camera

Endpoint: PUT /api/cameras/:id

Authentication: Required

Description: Update camera configuration.

URL Parameters:

• id (number, required): Camera ID

Request Body Schema:

{
  "camera_name": "Updated Deck Camera",
  "rtsp_url": "rtsp://newuser:newpass@192.168.1.105:554/stream1"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "camera_name": "Updated Deck Camera",
  "rtsp_url": "rtsp://newuser:newpass@192.168.1.105:554/stream1",
  "last_snapshot_url": "https://s3.example.com/snapshots/camera-1-latest.jpg",
  "webhook_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:45:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/cameras/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "camera_name": "Updated Deck Camera"
  }'

---

5. Delete Camera

Endpoint: DELETE /api/cameras/:id

Authentication: Required

Description: Delete a camera feed.

URL Parameters:

• id (number, required): Camera ID

Response Schema (200 OK):

{
  "success": true,
  "message": "Camera deleted successfully"
}

Example cURL:

curl -X DELETE https://api.example.com/api/cameras/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

6. Update Camera Snapshot (Webhook)

Endpoint: POST /api/cameras/:id/webhook

Authentication: Optional (uses webhook token)

Description: Home Assistant integration - update snapshot URL via webhook. Can be authenticated with webhook_token as query parameter instead of JWT.

URL Parameters:

• id (number, required): Camera ID
• token (string, required, as query param): Webhook token

Request Body Schema:

{
  "snapshot_url": "https://s3.example.com/snapshots/camera-1-2025-01-20-10-30.jpg",
  "event_type": "motion_detected"
}

Response Schema (200 OK):

{
  "success": true,
  "message": "Snapshot updated successfully",
  "last_snapshot_url": "https://s3.example.com/snapshots/camera-1-2025-01-20-10-30.jpg"
}

Example cURL:

curl -X POST "https://api.example.com/api/cameras/1/webhook?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_url": "https://s3.example.com/snapshots/camera-1-2025-01-20-10-30.jpg",
    "event_type": "motion_detected"
  }'

---

7. List Cameras (Boat View)

Endpoint: GET /api/cameras/:boatId/list

Authentication: Required

Description: Get all cameras for a boat with full details (alias for endpoint 2).

URL Parameters:

• boatId (number, required): Boat ID

Response Schema (200 OK):

{
  "boat_id": 123,
  "cameras": [
    {
      "id": 1,
      "camera_name": "Front Deck Camera",
      "rtsp_url": "rtsp://user:pass@192.168.1.100:554/stream1",
      "last_snapshot_url": "https://s3.example.com/snapshots/camera-1-latest.jpg",
      "webhook_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
    }
  ],
  "count": 1
}

Example cURL:

curl -X GET https://api.example.com/api/cameras/123/list \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Contacts Endpoints (7)

Manage marina, mechanic, and vendor contacts.

1. Create Contact

Endpoint: POST /api/contacts

Authentication: Required

Description: Create a new contact in an organization.

Request Body Schema:

{
  "organization_id": 456,
  "name": "Marina Mechanics Inc",
  "type": "mechanic",
  "phone": "+34-900-123-456",
  "email": "info@marinamech.es",
  "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
  "notes": "Specialized in diesel engine repairs"
}

Response Schema (201 Created):

{
  "id": 1,
  "organization_id": 456,
  "name": "Marina Mechanics Inc",
  "type": "mechanic",
  "phone": "+34-900-123-456",
  "email": "info@marinamech.es",
  "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
  "notes": "Specialized in diesel engine repairs",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Marina Mechanics Inc",
    "type": "mechanic",
    "phone": "+34-900-123-456",
    "email": "info@marinamech.es"
  }'

---

2. List Contacts by Organization

Endpoint: GET /api/contacts/:organizationId

Authentication: Required

Description: Get all contacts for an organization.

URL Parameters:

• organizationId (number, required): Organization ID

Query Parameters:

• type (string, optional): Filter by type (marina/mechanic/vendor/other)

Response Schema (200 OK):

[
  {
    "id": 1,
    "organization_id": 456,
    "name": "Marina Mechanics Inc",
    "type": "mechanic",
    "phone": "+34-900-123-456",
    "email": "info@marinamech.es",
    "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
    "notes": "Specialized in diesel engine repairs",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/contacts/456?type=mechanic" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

3. Get Contact Details

Endpoint: GET /api/contacts/:id

Authentication: Required

Description: Get details of a specific contact.

URL Parameters:

• id (number, required): Contact ID

Response Schema (200 OK):

{
  "id": 1,
  "organization_id": 456,
  "name": "Marina Mechanics Inc",
  "type": "mechanic",
  "phone": "+34-900-123-456",
  "email": "info@marinamech.es",
  "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
  "notes": "Specialized in diesel engine repairs",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X GET https://api.example.com/api/contacts/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

4. Filter Contacts by Type

Endpoint: GET /api/contacts/type/:type

Authentication: Required

Description: Get contacts filtered by type.

URL Parameters:

• type (string, required): Contact type (marina/mechanic/vendor/other)

Query Parameters:

• organization_id (number, optional): Filter by organization

Response Schema (200 OK):

[
  {
    "id": 1,
    "organization_id": 456,
    "name": "Marina Mechanics Inc",
    "type": "mechanic",
    "phone": "+34-900-123-456",
    "email": "info@marinamech.es",
    "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
    "notes": "Specialized in diesel engine repairs",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/contacts/type/mechanic?organization_id=456" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

5. Search Contacts

Endpoint: GET /api/contacts/search

Authentication: Required

Description: Search contacts by name or other fields.

Query Parameters:

• q (string, required): Search query
• organization_id (number, optional): Filter by organization
• type (string, optional): Filter by type

Response Schema (200 OK):

[
  {
    "id": 1,
    "organization_id": 456,
    "name": "Marina Mechanics Inc",
    "type": "mechanic",
    "phone": "+34-900-123-456",
    "email": "info@marinamech.es",
    "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
    "notes": "Specialized in diesel engine repairs",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/contacts/search?q=Marina&organization_id=456" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

6. Update Contact

Endpoint: PUT /api/contacts/:id

Authentication: Required

Description: Update a contact.

URL Parameters:

• id (number, required): Contact ID

Request Body Schema:

{
  "name": "Marina Mechanics Inc - Updated",
  "phone": "+34-900-999-999",
  "email": "support@marinamech.es"
}

Response Schema (200 OK):

{
  "id": 1,
  "organization_id": 456,
  "name": "Marina Mechanics Inc - Updated",
  "type": "mechanic",
  "phone": "+34-900-999-999",
  "email": "support@marinamech.es",
  "address": "Port Avenue 42, Puerto de Sóller, Mallorca",
  "notes": "Specialized in diesel engine repairs",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:45:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/contacts/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+34-900-999-999"
  }'

---

7. Delete Contact

Endpoint: DELETE /api/contacts/:id

Authentication: Required

Description: Delete a contact.

URL Parameters:

• id (number, required): Contact ID

Response Schema (200 OK):

{
  "success": true,
  "message": "Contact deleted successfully"
}

Example cURL:

curl -X DELETE https://api.example.com/api/contacts/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Expenses Endpoints (8)

Track boat expenses with multi-user splitting and OCR receipt processing.

1. Create Expense

Endpoint: POST /api/expenses

Authentication: Required

Description: Create a new expense with optional receipt upload.

Request Body Schema:

{
  "boat_id": 123,
  "amount": 250.50,
  "currency": "EUR",
  "date": "2025-01-15",
  "category": "Fuel",
  "receipt_url": "/uploads/receipts/expense-1.pdf",
  "split_users": {
    "user1": 0.5,
    "user2": 0.5
  },
  "notes": "Diesel fuel for Mediterranean crossing"
}

Response Schema (201 Created):

{
  "id": 1,
  "boat_id": 123,
  "amount": 250.50,
  "currency": "EUR",
  "date": "2025-01-15",
  "category": "Fuel",
  "receipt_url": "/uploads/receipts/expense-1.pdf",
  "ocr_text": null,
  "split_users": {
    "user1": 0.5,
    "user2": 0.5
  },
  "approval_status": "pending",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/expenses \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "boat_id": 123,
    "amount": 250.50,
    "currency": "EUR",
    "date": "2025-01-15",
    "category": "Fuel",
    "split_users": {
      "user1": 0.5,
      "user2": 0.5
    }
  }'

---

2. List Expenses by Boat

Endpoint: GET /api/expenses/:boatId

Authentication: Required

Description: Get all expenses for a boat.

URL Parameters:

• boatId (number, required): Boat ID

Query Parameters:

• category (string, optional): Filter by category
• start_date (string, optional): Filter from date (YYYY-MM-DD)
• end_date (string, optional): Filter to date (YYYY-MM-DD)

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "amount": 250.50,
    "currency": "EUR",
    "date": "2025-01-15",
    "category": "Fuel",
    "receipt_url": "/uploads/receipts/expense-1.pdf",
    "ocr_text": "TOTAL: €250.50",
    "split_users": {
      "user1": 0.5,
      "user2": 0.5
    },
    "approval_status": "approved",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T12:00:00Z"
  }
]

Example cURL:

curl -X GET "https://api.example.com/api/expenses/123?category=Fuel" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

3. List Pending Expenses

Endpoint: GET /api/expenses/:boatId/pending

Authentication: Required

Description: Get expenses awaiting approval.

URL Parameters:

• boatId (number, required): Boat ID

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "amount": 250.50,
    "currency": "EUR",
    "date": "2025-01-15",
    "category": "Fuel",
    "receipt_url": "/uploads/receipts/expense-1.pdf",
    "ocr_text": "TOTAL: €250.50",
    "split_users": {
      "user1": 0.5,
      "user2": 0.5
    },
    "approval_status": "pending",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET https://api.example.com/api/expenses/123/pending \
  -H "Authorization: Bearer YOUR_TOKEN"

---

4. Get Split Expenses

Endpoint: GET /api/expenses/:boatId/split

Authentication: Required

Description: Get expenses with split details and calculations.

URL Parameters:

• boatId (number, required): Boat ID

Response Schema (200 OK):

[
  {
    "id": 1,
    "boat_id": 123,
    "amount": 250.50,
    "currency": "EUR",
    "date": "2025-01-15",
    "category": "Fuel",
    "split_users": {
      "user1": {
        "share": 0.5,
        "amount_owed": 125.25
      },
      "user2": {
        "share": 0.5,
        "amount_owed": 125.25
      }
    },
    "approval_status": "pending",
    "approvals": {
      "user1": true,
      "user2": false
    },
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  }
]

Example cURL:

curl -X GET https://api.example.com/api/expenses/123/split \
  -H "Authorization: Bearer YOUR_TOKEN"

---

5. Update Expense

Endpoint: PUT /api/expenses/:id

Authentication: Required

Description: Update an expense.

URL Parameters:

• id (number, required): Expense ID

Request Body Schema:

{
  "amount": 260.00,
  "category": "Fuel & Marina",
  "notes": "Updated notes"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "amount": 260.00,
  "currency": "EUR",
  "date": "2025-01-15",
  "category": "Fuel & Marina",
  "receipt_url": "/uploads/receipts/expense-1.pdf",
  "ocr_text": "TOTAL: €260.00",
  "split_users": {
    "user1": 0.5,
    "user2": 0.5
  },
  "approval_status": "pending",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:45:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/expenses/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 260.00,
    "category": "Fuel & Marina"
  }'

---

6. Approve Expense

Endpoint: PUT /api/expenses/:id/approve

Authentication: Required

Description: Approve an expense (multi-user approval workflow).

URL Parameters:

• id (number, required): Expense ID

Request Body Schema:

{
  "user_id": "user1",
  "approval_status": "approved"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "amount": 250.50,
  "currency": "EUR",
  "date": "2025-01-15",
  "category": "Fuel",
  "split_users": {
    "user1": 0.5,
    "user2": 0.5
  },
  "approval_status": "approved",
  "approvals": {
    "user1": true,
    "user2": true
  },
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T12:15:00Z"
}

Example cURL:

curl -X PUT https://api.example.com/api/expenses/1/approve \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user1",
    "approval_status": "approved"
  }'

---

7. Delete Expense

Endpoint: DELETE /api/expenses/:id

Authentication: Required

Description: Delete an expense.

URL Parameters:

• id (number, required): Expense ID

Response Schema (200 OK):

{
  "success": true,
  "message": "Expense deleted successfully"
}

Example cURL:

curl -X DELETE https://api.example.com/api/expenses/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

8. Process Receipt OCR

Endpoint: POST /api/expenses/:id/ocr

Authentication: Required

Description: Extract text from receipt image using OCR.

URL Parameters:

• id (number, required): Expense ID

Request Body Schema:

{
  "provider": "google-vision"
}

Response Schema (200 OK):

{
  "id": 1,
  "boat_id": 123,
  "amount": 250.50,
  "currency": "EUR",
  "date": "2025-01-15",
  "category": "Fuel",
  "receipt_url": "/uploads/receipts/expense-1.pdf",
  "ocr_text": "TOTAL: €250.50\nFUEL TYPE: DIESEL\nQUANTITY: 500L\nPRICE/L: €0.50\nDATE: 2025-01-15",
  "split_users": {
    "user1": 0.5,
    "user2": 0.5
  },
  "approval_status": "pending",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T11:00:00Z"
}

Example cURL:

curl -X POST https://api.example.com/api/expenses/1/ocr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google-vision"
  }'

---

Response Codes

Code	Status	Meaning
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content to return
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate entry)
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Service temporarily unavailable

---

Error Handling

Error Response Format

All errors follow this standard format:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "timestamp": "2025-01-20T10:30:00Z",
  "request_id": "req-12345678"
}

Common Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Missing or invalid request parameters
AUTHENTICATION_FAILED	401	Authentication token missing or invalid
AUTHORIZATION_FAILED	403	User lacks required permissions
NOT_FOUND	404	Requested resource not found
DUPLICATE_ENTRY	409	Resource already exists
VALIDATION_ERROR	422	Validation constraint violated
RATE_LIMIT_EXCEEDED	429	Request rate limit exceeded
INTERNAL_ERROR	500	Internal server error

Example Error Response

curl -X GET https://api.example.com/api/inventory/999 \
  -H "Authorization: Bearer INVALID_TOKEN"

# Response:
{
  "success": false,
  "error": "Boat not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-20T10:30:00Z",
  "request_id": "req-87654321"
}

---

Rate Limiting

All API endpoints are subject to rate limiting.

Rate Limit Headers

Response headers include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642663800

Default Limits

• Per User: 1000 requests per 15 minutes
• Per IP: 100 requests per 15 minutes (unauthenticated)
• Per Endpoint: 100 requests per 15 minutes

Rate Limit Exceeded Response

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 42,
  "timestamp": "2025-01-20T10:30:00Z"
}

---

Endpoint Summary

Module	Method	Endpoint	Auth	Purpose
Inventory	POST	/api/inventory	✓	Create item
	GET	/api/inventory/:boatId	✓	List items
	GET	/api/inventory/:boatId/:itemId	✓	Get details
	PUT	/api/inventory/:id	✓	Update item
	DELETE	/api/inventory/:id	✓	Delete item
Maintenance	POST	/api/maintenance	✓	Create record
	GET	/api/maintenance/:boatId	✓	List records
	GET	/api/maintenance/:boatId/upcoming	✓	Get upcoming
	PUT	/api/maintenance/:id	✓	Update record
	DELETE	/api/maintenance/:id	✓	Delete record
Cameras	POST	/api/cameras	✓	Register camera
	GET	/api/cameras/:boatId	✓	List cameras
	GET	/api/cameras/:id	✓	Get details
	PUT	/api/cameras/:id	✓	Update camera
	DELETE	/api/cameras/:id	✓	Delete camera
	POST	/api/cameras/:id/webhook	△	Webhook update
	GET	/api/cameras/:boatId/list	✓	List cameras
Contacts	POST	/api/contacts	✓	Create contact
	GET	/api/contacts/:organizationId	✓	List contacts
	GET	/api/contacts/:id	✓	Get details
	GET	/api/contacts/type/:type	✓	Filter by type
	GET	/api/contacts/search	✓	Search contacts
	PUT	/api/contacts/:id	✓	Update contact
	DELETE	/api/contacts/:id	✓	Delete contact
Expenses	POST	/api/expenses	✓	Create expense
	GET	/api/expenses/:boatId	✓	List expenses
	GET	/api/expenses/:boatId/pending	✓	Get pending
	GET	/api/expenses/:boatId/split	✓	Get splits
	PUT	/api/expenses/:id	✓	Update expense
	PUT	/api/expenses/:id/approve	✓	Approve expense
	DELETE	/api/expenses/:id	✓	Delete expense
	POST	/api/expenses/:id/ocr	✓	Process OCR

Auth: ✓ = JWT required, △ = Webhook token or JWT

---

Support & Version History

API Version: 1.0.0 Last Updated: 2025-11-14 Status: Production Ready

Version History

Version	Date	Changes
1.0.0	2025-11-14	Initial release with 32 endpoints

Support

For API support, issues, or questions:

• GitHub Issues: https://github.com/navidocs/api/issues
• Email: api-support@example.com
• Documentation: https://docs.example.com/api

---

End of API Documentation