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"
}