calendar_public_api

TriLuna Calendar Public API

Overview

The TriLuna Calendar Public API allows you to integrate your calendar availability with external services like Zapier, custom applications, and automation tools.

Authentication

All requests require an API token obtained from your TriLuna profile page at https://triluna.app/profile.

API Token Scopes Required

Read Calendar: read:calendar or read:own_profile
Write Calendar: write:calendar or write:own_profile

Authentication Methods

Bearer Token (Recommended):

Authorization: Bearer YOUR_API_TOKEN

X-API-Key Header:

X-API-Key: YOUR_API_TOKEN

Base URL

https://api.triluna.app/api/public

Endpoints

1. Get Calendar Availability

GET /calendar/availability

Get your calendar availability entries for a date range.

Query Parameters:

start_date (optional): Start date in YYYY-MM-DD format
end_date (optional): End date in YYYY-MM-DD format
include_recurring (optional): Set to ‘true’ to include recurring availability

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.triluna.app/api/public/calendar/availability?start_date=2025-09-01&end_date=2025-09-30&include_recurring=true"

Response:

{
  "availability": [
    {
      "id": 1,
      "date": "2025-09-01",
      "start_time": "09:00:00",
      "end_time": "17:00:00", 
      "is_available": true,
      "title": "Available for meetings",
      "notes": null,
      "created_at": "2025-09-01T10:00:00.000Z",
      "updated_at": "2025-09-01T10:00:00.000Z"
    }
  ],
  "recurring": [
    {
      "id": 1,
      "day_of_week": 1,
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_available": true,
      "title": "Regular business hours"
    }
  ]
}

2. Create Calendar Entry

POST /calendar/availability

Create a new calendar availability entry.

Request Body:

{
  "date": "2025-09-01",
  "start_time": "14:00",
  "end_time": "15:00",
  "is_available": false,
  "title": "Client meeting",
  "notes": "Important client consultation"
}

Required Fields:

date: Date in YYYY-MM-DD format
start_time: Time in HH:MM format
end_time: Time in HH:MM format

Optional Fields:

is_available: Boolean (default: true)
title: String description
notes: Additional notes

Response:

{
  "success": true,
  "availability": {
    "id": 123,
    "date": "2025-09-01",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "is_available": false,
    "title": "Client meeting",
    "notes": "Important client consultation"
  }
}

3. Update Calendar Entry

PUT /calendar/availability/:id

Update an existing calendar entry.

Example:

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated meeting title", "is_available": true}' \
  "https://api.triluna.app/api/public/calendar/availability/123"

4. Delete Calendar Entry

DELETE /calendar/availability/:id

Delete a calendar entry.

Example:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.triluna.app/api/public/calendar/availability/123"

Response:

{
  "success": true,
  "message": "Calendar entry deleted successfully"
}

5. Get Recurring Availability

GET /calendar/recurring

Get your recurring weekly availability patterns.

Response:

{
  "recurring": [
    {
      "id": 1,
      "day_of_week": 1,
      "start_time": "09:00:00", 
      "end_time": "17:00:00",
      "is_available": true,
      "title": "Regular business hours"
    }
  ]
}

6. Create Recurring Availability

POST /calendar/recurring

Create a recurring weekly availability pattern.

Request Body:

{
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00", 
  "is_available": true,
  "title": "Monday business hours"
}

Day of Week Values:

0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday

7. Delete Recurring Availability

DELETE /calendar/recurring/:id

Delete a recurring availability pattern.

Zapier Integration

Webhook Setup

Use these endpoints for Zapier triggers and actions:

Zapier Trigger Example (Get Calendar Changes):

URL: https://api.triluna.app/api/public/calendar/availability
Method: GET
Auth: API Key in header
Polling: Check for new/updated entries

Zapier Action Example (Create Calendar Entry):

URL: https://api.triluna.app/api/public/calendar/availability
Method: POST
Auth: API Key in header
Body: Calendar entry JSON

Error Responses

401 Unauthorized

{
  "error": "API key required", 
  "message": "Provide API key in Authorization header (Bearer token) or X-API-Key header"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "API token requires read:calendar or write:calendar scope"
}

409 Conflict

{
  "error": "Time slot conflict",
  "message": "Time slot conflicts with existing availability",
  "conflicts": [{"id": 456, "start_time": "14:00:00", "end_time": "15:00:00"}]
}

Calendar Modes

TriLuna supports two calendar modes:

Available Times Mode

Set specific times when you’re available
is_available: true entries mark open slots
Agents/systems only book in marked available times

Unavailable Times Mode

Set specific times when you’re NOT available
is_available: false entries mark blocked slots
Agents/systems avoid marked unavailable times (default 8 AM - 8 PM booking window)

Rate Limiting

1000 requests per hour per API token
Rate limit headers included in responses
429 status returned when limit exceeded

Best Practices

Use specific date ranges in GET requests for better performance
Include meaningful titles for calendar entries
Check for conflicts before creating overlapping entries
Use recurring availability for regular weekly patterns
Handle 409 conflicts gracefully in your integration

Getting Started

Get API Token: Visit https://triluna.app/profile
Set Scopes: Include read:calendar and write:calendar
Test Access: Make a GET request to /calendar/availability
Create Integration: Use with Zapier, webhooks, or custom apps

Support

For API support or integration help:

📧 Email: support@triluna.app
📚 Documentation: This guide
🔧 Test: Use browser dev tools to test API calls