Calendar API Integration Guide

Getting Started with Calendar API

The TriLuna Calendar API allows you to programmatically manage your availability and integrate with external services like Zapier, scheduling tools, and custom applications.

Step 1: Get Your API Token

1. Log into your TriLuna dashboard
2. Go to Profile Settings (click your profile dropdown)
3. Scroll down to the API Access section
4. Click “Generate API Token”
5. Select the required scopes:
   • read:calendar - To read your calendar data
   • write:calendar - To create/update calendar entries
6. Copy and securely store your API token

Step 2: Test Your API Access

Before setting up integrations, test that your API token works:

Using cURL (Command Line):

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.triluna.app/api/public/calendar/availability"

Using Postman or Similar Tool:

• URL: https://api.triluna.app/api/public/calendar/availability
• Method: GET
• Headers: Authorization: Bearer YOUR_API_TOKEN

Calendar API Operations

Reading Your Calendar

Get All Availability:

GET /api/public/calendar/availability

Returns all your calendar entries. You can filter by date range and include recurring patterns.

Query Parameters:

• start_date: Filter from this date (YYYY-MM-DD format)
• end_date: Filter to this date (YYYY-MM-DD format)
• include_recurring: Set to ‘true’ to include weekly recurring patterns

Example Response:

{
  "availability": [
    {
      "id": 123,
      "date": "2025-09-01",
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "is_available": true,
      "title": "Available for meetings",
      "notes": null
    }
  ]
}

Creating Calendar Entries

Create Availability Slot:

POST /api/public/calendar/availability

Create a new calendar entry to mark available or unavailable times.

Required Fields:

• date: Date in YYYY-MM-DD format
• start_time: Start time in HH:MM format (24-hour)
• end_time: End time in HH:MM format (24-hour)

Optional Fields:

• is_available: true for available, false for unavailable (default: true)
• title: Description of the time slot
• notes: Additional details

Example Request:

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

Updating and Deleting Entries

Update Calendar Entry:

PUT /api/public/calendar/availability/123

Update an existing calendar entry by its ID.

Delete Calendar Entry:

DELETE /api/public/calendar/availability/123

Remove a calendar entry completely.

Zapier Integration Guide

Setting Up Zapier Webhook

Zapier can trigger actions based on your calendar changes or create calendar entries from other apps:

Zapier Trigger (Calendar Changes):

1. In Zapier, choose “Webhooks by Zapier” as trigger
2. Select “Catch Hook” trigger type
3. Set up a polling webhook to check for calendar changes
4. Use URL: https://api.triluna.app/api/public/calendar/availability
5. Add header: Authorization: Bearer YOUR_API_TOKEN

Zapier Action (Create Calendar Entry):

1. In Zapier, choose “Webhooks by Zapier” as action
2. Select “POST” action type
3. URL: https://api.triluna.app/api/public/calendar/availability
4. Method: POST
5. Headers: Authorization: Bearer YOUR_API_TOKEN
6. Data: Map fields from trigger (date, start_time, end_time, etc.)

Common Zapier Use Cases

Google Calendar Sync:

Trigger: New Google Calendar event Action: Create TriLuna unavailable time Result: Google Calendar blocks automatically sync to TriLuna

Meeting Booking Automation:

Trigger: New Calendly booking Action: Create TriLuna unavailable time Result: External bookings automatically block TriLuna availability

CRM Integration:

Trigger: New CRM appointment Action: Create TriLuna calendar entry Result: Sales meetings automatically appear in TriLuna calendar

Understanding Calendar Modes

TriLuna supports two calendar approaches that affect how your API integrations should work:

Available Times Mode

How it works: You explicitly mark when you’re available for appointments.

API Usage for Available Times:

• Create available slots: is_available: true
• Remove availability: Delete or set is_available: false
• Integration logic: Only create available entries for open times

Zapier Example (Available Times):

When you mark “free” time in Google Calendar > Create is_available: true entry in TriLuna

Unavailable Times Mode

How it works: You mark when you’re NOT available (default assumption is available 8 AM - 8 PM).

API Usage for Unavailable Times:

• Block time slots: is_available: false
• Remove blocks: Delete unavailable entries
• Integration logic: Only create entries to block time

Zapier Example (Unavailable Times):

When you have a Google Calendar event > Create is_available: false entry in TriLuna

Advanced Integration Examples

Recurring Weekly Patterns

Create recurring weekly availability using the recurring endpoints:

Set Regular Business Hours:

POST /api/public/calendar/recurring
{
  "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

Two-Way Calendar Sync

For complete calendar synchronization, set up both trigger and action Zaps:

TriLuna to External Calendar:

1. Trigger: Poll TriLuna calendar API for changes
2. Action: Create/update external calendar events
3. Filter: Only sync specific types (meetings, unavailable times)

External Calendar to TriLuna:

1. Trigger: New/updated external calendar event
2. Action: Create TriLuna calendar entry
3. Mapping: Map external event fields to TriLuna format

API Response Examples

Successful Creation:

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

Conflict Error:

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

Permission Error:

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

Troubleshooting

Common Issues and Solutions

Authentication Failed:

• Check token: Ensure API token is copied correctly
• Check scopes: Token must have calendar read/write permissions
• Check expiration: API tokens can expire
• Check format: Use “Bearer TOKEN” format in Authorization header

Time Format Errors:

• Date format: Must be YYYY-MM-DD (e.g., 2025-09-01)
• Time format: Must be HH:MM in 24-hour format (e.g., 14:30)
• Time zones: All times are in your local timezone

Conflict Errors:

• Check existing entries: Use GET request first to see current calendar
• Adjust times: Modify start/end times to avoid overlaps
• Update instead: Use PUT to modify existing entries

Integration Best Practices

For Zapier Integrations:

1. Test with single events first before enabling bulk sync
2. Use meaningful titles to identify the source of calendar entries
3. Handle conflicts gracefully by checking existing entries
4. Set up error notifications when API calls fail
5. Use date filters to avoid syncing old events

For Custom Applications:

1. Implement proper error handling for all API responses
2. Cache token validation to avoid repeated auth checks
3. Use appropriate scopes - don’t request more permissions than needed
4. Respect rate limits (1000 requests per hour)
5. Use bulk operations when possible for efficiency

API Reference Summary

Base URL

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

Authentication

Authorization: Bearer YOUR_API_TOKEN

Available Endpoints

• GET /calendar/availability - Read calendar entries
• POST /calendar/availability - Create calendar entry
• PUT /calendar/availability/:id - Update calendar entry
• DELETE /calendar/availability/:id - Delete calendar entry
• GET /calendar/recurring - Read recurring patterns
• POST /calendar/recurring - Create recurring pattern
• DELETE /calendar/recurring/:id - Delete recurring pattern

Required Scopes

• read:calendar - Read calendar data
• write:calendar - Create/update/delete calendar entries

Related Articles

• Calendar User Guide
• How to Set Agent Behavior

Need Help?

Calendar API integration can be complex. Get support for your specific use case:

• Email our integration team
• Use the chat widget for quick API questions
• Schedule an API consultation through your dashboard
• Browse our complete help documentation