Skip to main content
POST
/
api
/
v1
/
calendar
/
events
/
create
{
  "id": 123,
  "uuid": "<string>",
  "title": "<string>",
  "start_time": "<string>",
  "end_time": "<string>",
  "status": "<string>",
  "ics_url": "<string>",
  "message": "<string>",
  "error": "<string>"
}
Create a new calendar event with the specified information.

​
Request Body

​
title
string
required
Event title.
​
description
string
Event description.
​
start_time
string
required
Event start time.
​
end_time
string
required
Event end time.
​
event_type
string
default:"meeting"
Type of event. One of: meeting, appointment, busy, voice_call, video_call.
​
status
string
default:"scheduled"
Event status. One of: scheduled, confirmed.
​
location
string
Event location.
​
customer_name
string
Customer name.
​
customer_email
string
Customer email.
​
customer_phone
string
Customer phone number.
​
customer_notes
string
Notes about the customer or appointment.
​
has_video_conference
boolean
default:false
Whether to enable video conferencing.
​
video_conference_url
string
URL for video conferencing.
​
video_conference_provider
string
Provider of video conferencing (e.g., Zoom, Google Meet, etc.).
​
is_reminder_enabled
boolean
default:true
Whether to enable reminders.
​
remind_before_minutes
integer
default:60
How many minutes before the event to send a reminder.
​
ai_agent_id
integer
ID of the AI agent to associate with this event.
​
team_id
integer
ID of the team to associate with this event.
​
created_by_ai_agent
boolean
default:false
Whether this event was created by an AI agent.
​
sync_external_calendars
boolean
default:true
Whether to sync this event with connected external calendars.
​
send_notifications
boolean
default:true
Whether to send notifications about this event.

​
Response

​
id
integer
Event ID.
​
uuid
string
Event UUID.
​
title
string
Event title.
​
start_time
string
Event start time.
​
end_time
string
Event end time.
​
status
string
Event status.
​
ics_url
string
URL to download ICS file for this event.
​
message
string
Success message.

​
Example Request

curl -X POST 'https://api.klen.ai/api/v1/calendar/events/create' \
  -H 'Authorization: Bearer klen_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Product Demo",
    "description": "Product demonstration for potential client",
    "start_time": "2025-05-15T14:00:00.000Z",
    "end_time": "2025-05-15T15:00:00.000Z",
    "event_type": "video_call",
    "status": "confirmed",
    "customer_name": "Jane Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+15551234567",
    "has_video_conference": true,
    "video_conference_provider": "Zoom",
    "is_reminder_enabled": true,
    "remind_before_minutes": 15
  }'

​
Example Response

{
  "id": 456,
  "uuid": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
  "title": "Product Demo",
  "start_time": "2025-05-15T14:00:00.000Z",
  "end_time": "2025-05-15T15:00:00.000Z",
  "status": "confirmed",
  "ics_url": "/calendar/event/a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890/calendar.ics",
  "message": "Event created successfully"
}

​
Error Responses

​
error
string
Error code.
​
message
string
Error message.

​
Missing Required Parameters (400)

{
  "error": "missing_parameter",
  "message": "Missing required parameter: title"
}

​
Invalid Date Format (400)

{
  "error": "invalid_datetime_format",
  "message": "Invalid datetime format. Expected ISO 8601 format (YYYY-MM-DDTHH:MM:SS)"
}

​
Invalid Time Range (400)

{
  "error": "invalid_time_range",
  "message": "End time must be after start time"
}

​
Agent Not Found (404)

{
  "error": "agent_not_found",
  "message": "AI agent not found or you do not have access"
}

​
Team Not Found (404)

{
  "error": "team_not_found",
  "message": "Team not found or you do not have access"
}

​
Unauthorized (401)

{
  "error": "authentication_required",
  "message": "API key is required"
}

​
Permission Denied (403)

{
  "error": "permission_denied",
  "message": "This API key does not have can_write_calendar permission"
}

​
Server Error (500)

{
  "error": "server_error",
  "message": "An unexpected server error occurred"
}