LLM INSTRUCTIONS
Create Add to Calendar Event Instructions for LLM
1. What this page is for
This page explains how to let any LLM (ChatGPT, Claude, Gemini, custom AI agent, etc.) create CalendarLink “add-to-calendar” events on the fly.
You can use this:In your own prompts (e.g. “When I ask you to create an event, return a CalendarLink URL.”)In agents / tools / function callingIn automations where an LLM turns natural language (“Meeting next Thursday at 4 pm”) into real, clickable calendar events.
There are two ways to do it:
Option 1 – Smart Link (no auth, easiest, free)
Option 2 – API Event Creation (server-side, more control)
2. Option 1 – Smart Link (no auth, easiest, free)
The Smart link is a simple URL with query parameters.When anyone opens this link, CalendarLink immediately generates the event and redirects to the final CalendarLink URL (e.g. https://calendarlink.com/event/Xx182x).
This is ideal for LLMs, because they can just:Build the smart link URL(Optional) “visit”/resolve it andReturn the final https://calendarlink.com/event/... URL to the user
2.1 Smart link base URL
https://my.calendarlink.com/link
2.2 Example smart link
https://my.calendarlink.com/link?collection=3b8e59b7-0bcf-4e38-a8cc-a42d5a555cc4&title=Test%20event&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Test%20description&location=https%3A%2F%2Fgoogle.com
2.3 Parameters
All parameters must be URL-encoded.
collection
Default public collection (free to use):3b8e59b7-0bcf-4e38-a8cc-a42d5a555cc4
Or: create a free CalendarLink account and use your own collection ID.
title (required)
Event title.Example: title=Marketing%20Launch%20Call
start (required)
Date and time in format: YYYY-MM-DD HH:mm
Example (not encoded): 2025-12-21 16:00
URL-encoded: start=2025-12-21%2016%3A00
duration (required)
Event duration in minutes.
Example: duration=120 for 2 hours.
timezone (required) IANA timezone string.
Example: Europe/Amsterdam, America/New_York, Asia/Tokyo.
URL example: timezone=Europe%2FAmsterdam
description (optional)
Long text description.Can be empty, but omit the parameter if you don’t need it.
Example: description=Quarterly%20planning%20session
location (optional)
For online events, use a URLExample: https://zoom.us/…For physical events, use an addressExample: Street%20name%2013%2C%20New%20York%2C%20New%20York
Omit if not needed.
2.4 What an LLM should do (instructions)
You can embed the following instructions into a system prompt / tool description:
When the user asks you to create an event, generate a CalendarLink smart link.
Use this base URL: https://my.calendarlink.com/linkUse collection=190fceeb-e934-4425-8590-ce0bdbcba594 (or another collection ID the user provides).
Add the following URL-encoded query parameters:title: required event titlestart: YYYY-MM-DD HH:mm in the user’s timezoneduration: in minutestimezone: an IANA timezone, e.g. Europe/AmsterdamOptional: description, location
Return either:The full smart link itself, or Even better: resolve the smart link and return the final redirect URL, which looks like https://calendarlink.com/event/XYZ123.
Always ensure proper URL encoding for spaces and special characters.
2.5 Example LLM output (smart link)
This is your smart links that generates the event instantly:
https://my.calendarlink.com/link?collection=190fceeb-e934-4425-8590-ce0bdbcba594&title=Team%20Meeting&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Quarterly%20planning%20session&location=Conference%20Room%20A
Visit the url and copy the url in the browser if you want to share this event (e.g. https://calendarlink.com/event/your-event).
2.6 Example LLM output (final redirect URL) If the LLM (or your backend agent) can follow redirects:
This is your smart links that generates the event instantly:
https://my.calendarlink.com/link?collection=190fceeb-e934-4425-8590-ce0bdbcba594&title=Team%20Meeting&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Quarterly%20planning%20session&location=Conference%20Room%20A
This is your final url you can share with anyone: https://calendarlink.com/event/your-event
Option 2 – Generate via API (server-side)
Use this option if you want to create CalendarLink events from your own backend instead of directly from the LLM. The LLM or agent can describe the event in natural language, and your server can call the CalendarLink API to create an add-to-calendar link and return it to the user.
EndpointPOST https://my.calendarlink.com/api/v1/{organisationId}/event
Public organisation ID (demo)3f7c05f4-da89-4937-8b0b-f345d3adb01e(You can also create a free CalendarLink account and replace this with your own organisation ID.)
Default collection ID4a2a4e56-52ba-4d85-8817-bbb56efc244a(Use this as the default collection_id, or replace it with your own.)
AuthenticationUse a Bearer token in the Authorization header.
Authorization: Bearer NkZBAkSnZPkP9zqDhE5TrTMvvL5lXrXCUPiaKEw1b2486b6cContent-Type: application/json
Important: In a production setup you normally keep this API key on your server (not exposed in client-side code or directly to the LLM). The LLM describes the request, your backend actually calls the API.
JSON body parameters
collection_id (optional, UUID)– A CalendarLink collection to organize the event in.– Must be a valid UUID.– You can use the default collection: 4a2a4e56-52ba-4d85-8817-bbb56efc244a
title (required, string)– Event title.– 1–200 characters (after trimming).– Cannot be empty.
description (optional, string)– Long description of the event.– Max 5000 characters.– Only sent if it has a value (non-empty).
location (optional, string)– Where the event takes place.– For online events, use a URL (e.g. https://zoom.us/…).– For physical events, use an address (e.g. “Street name 13, New York, New York”).– Max 500 characters.– Only sent if it has a value (non-empty).
start (required, string)– Start date and time of the event.– Format: YYYY-MM-DD HH:MM– Example: “2025-12-21 16:00”
end (required, string)– End date and time of the event.– Format: YYYY-MM-DD HH:MM– Example: “2025-12-21 18:00”
timezone (required, string)– Timezone in IANA format.– Examples: “Europe/Amsterdam”, “America/New_York”, “Asia/Tokyo”.– 1–100 characters.
date_format (required, string)– Must always be: “Y-m-d H:i”– This tells the API how to interpret the start and end strings.
rsvp.enabled (optional, boolean)– Default: false.– Set to true if you want to enable RSVP functionality for this event.
Example HTTP request
POST https://my.calendarlink.com/api/v1/3f7c05f4-da89-4937-8b0b-f345d3adb01e/eventAuthorization: Bearer NkZBAkSnZPkP9zqDhE5TrTMvvL5lXrXCUPiaKEw1b2486b6cContent-Type: application/json
Body:
{“collection_id”: “4a2a4e56-52ba-4d85-8817-bbb56efc244a”,“title”: “Team Meeting”,“description”: “Quarterly planning session”,“location”: “Conference Room A”,“start”: “2025-12-21 16:00”,“end”: “2025-12-21 18:00”,“timezone”: “Europe/Amsterdam”,“date_format”: “Y-m-d H:i”,“rsvp”: {“enabled”: false}}
Rate limiting
– Maximum of 20 requests per hour per IP address.– If the limit is exceeded, the API returns HTTP 429 (Too Many Requests).– Retry after 3600 seconds.
Input validation
– Dates must match YYYY-MM-DD (e.g. “2025-12-21”).– Times must match HH:MM (e.g. “16:00”).– title cannot be empty after trimming whitespace.– collection_id must be a valid UUID if provided.– description and location are only sent if they have a real value (no empty strings).
Error handling
– 400 Bad Request: validation errors, with details about which field is invalid.– 429 Too Many Requests: rate limit exceeded.– 500 Internal Server Error: CalendarLink API error (message is sanitized).
Response
The API returns the CalendarLink event JSON, including the final add-to-calendar URL (for example: https://calendarlink.com/event/XYZ123). You can show this URL to the user directly, or feed it back into your LLM so the assistant can include a clickable “Add to Calendar” link in its response.
This page explains how to let any LLM (ChatGPT, Claude, Gemini, custom AI agent, etc.) create CalendarLink “add-to-calendar” events on the fly.
You can use this:In your own prompts (e.g. “When I ask you to create an event, return a CalendarLink URL.”)In agents / tools / function callingIn automations where an LLM turns natural language (“Meeting next Thursday at 4 pm”) into real, clickable calendar events.
There are two ways to do it:
Option 1 – Smart Link (no auth, easiest, free)
Option 2 – API Event Creation (server-side, more control)
2. Option 1 – Smart Link (no auth, easiest, free)
The Smart link is a simple URL with query parameters.When anyone opens this link, CalendarLink immediately generates the event and redirects to the final CalendarLink URL (e.g. https://calendarlink.com/event/Xx182x).
This is ideal for LLMs, because they can just:Build the smart link URL(Optional) “visit”/resolve it andReturn the final https://calendarlink.com/event/... URL to the user
2.1 Smart link base URL
https://my.calendarlink.com/link
2.2 Example smart link
https://my.calendarlink.com/link?collection=3b8e59b7-0bcf-4e38-a8cc-a42d5a555cc4&title=Test%20event&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Test%20description&location=https%3A%2F%2Fgoogle.com
2.3 Parameters
All parameters must be URL-encoded.
collection
Default public collection (free to use):3b8e59b7-0bcf-4e38-a8cc-a42d5a555cc4
Or: create a free CalendarLink account and use your own collection ID.
title (required)
Event title.Example: title=Marketing%20Launch%20Call
start (required)
Date and time in format: YYYY-MM-DD HH:mm
Example (not encoded): 2025-12-21 16:00
URL-encoded: start=2025-12-21%2016%3A00
duration (required)
Event duration in minutes.
Example: duration=120 for 2 hours.
timezone (required) IANA timezone string.
Example: Europe/Amsterdam, America/New_York, Asia/Tokyo.
URL example: timezone=Europe%2FAmsterdam
description (optional)
Long text description.Can be empty, but omit the parameter if you don’t need it.
Example: description=Quarterly%20planning%20session
location (optional)
For online events, use a URLExample: https://zoom.us/…For physical events, use an addressExample: Street%20name%2013%2C%20New%20York%2C%20New%20York
Omit if not needed.
2.4 What an LLM should do (instructions)
You can embed the following instructions into a system prompt / tool description:
When the user asks you to create an event, generate a CalendarLink smart link.
Use this base URL: https://my.calendarlink.com/linkUse collection=190fceeb-e934-4425-8590-ce0bdbcba594 (or another collection ID the user provides).
Add the following URL-encoded query parameters:title: required event titlestart: YYYY-MM-DD HH:mm in the user’s timezoneduration: in minutestimezone: an IANA timezone, e.g. Europe/AmsterdamOptional: description, location
Return either:The full smart link itself, or Even better: resolve the smart link and return the final redirect URL, which looks like https://calendarlink.com/event/XYZ123.
Always ensure proper URL encoding for spaces and special characters.
2.5 Example LLM output (smart link)
This is your smart links that generates the event instantly:
https://my.calendarlink.com/link?collection=190fceeb-e934-4425-8590-ce0bdbcba594&title=Team%20Meeting&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Quarterly%20planning%20session&location=Conference%20Room%20A
Visit the url and copy the url in the browser if you want to share this event (e.g. https://calendarlink.com/event/your-event).
2.6 Example LLM output (final redirect URL) If the LLM (or your backend agent) can follow redirects:
This is your smart links that generates the event instantly:
https://my.calendarlink.com/link?collection=190fceeb-e934-4425-8590-ce0bdbcba594&title=Team%20Meeting&start=2025-12-21%2016%3A00&duration=120&timezone=Europe%2FAmsterdam&description=Quarterly%20planning%20session&location=Conference%20Room%20A
This is your final url you can share with anyone: https://calendarlink.com/event/your-event
Option 2 – Generate via API (server-side)
Use this option if you want to create CalendarLink events from your own backend instead of directly from the LLM. The LLM or agent can describe the event in natural language, and your server can call the CalendarLink API to create an add-to-calendar link and return it to the user.
EndpointPOST https://my.calendarlink.com/api/v1/{organisationId}/event
Public organisation ID (demo)3f7c05f4-da89-4937-8b0b-f345d3adb01e(You can also create a free CalendarLink account and replace this with your own organisation ID.)
Default collection ID4a2a4e56-52ba-4d85-8817-bbb56efc244a(Use this as the default collection_id, or replace it with your own.)
AuthenticationUse a Bearer token in the Authorization header.
Authorization: Bearer NkZBAkSnZPkP9zqDhE5TrTMvvL5lXrXCUPiaKEw1b2486b6cContent-Type: application/json
Important: In a production setup you normally keep this API key on your server (not exposed in client-side code or directly to the LLM). The LLM describes the request, your backend actually calls the API.
JSON body parameters
collection_id (optional, UUID)– A CalendarLink collection to organize the event in.– Must be a valid UUID.– You can use the default collection: 4a2a4e56-52ba-4d85-8817-bbb56efc244a
title (required, string)– Event title.– 1–200 characters (after trimming).– Cannot be empty.
description (optional, string)– Long description of the event.– Max 5000 characters.– Only sent if it has a value (non-empty).
location (optional, string)– Where the event takes place.– For online events, use a URL (e.g. https://zoom.us/…).– For physical events, use an address (e.g. “Street name 13, New York, New York”).– Max 500 characters.– Only sent if it has a value (non-empty).
start (required, string)– Start date and time of the event.– Format: YYYY-MM-DD HH:MM– Example: “2025-12-21 16:00”
end (required, string)– End date and time of the event.– Format: YYYY-MM-DD HH:MM– Example: “2025-12-21 18:00”
timezone (required, string)– Timezone in IANA format.– Examples: “Europe/Amsterdam”, “America/New_York”, “Asia/Tokyo”.– 1–100 characters.
date_format (required, string)– Must always be: “Y-m-d H:i”– This tells the API how to interpret the start and end strings.
rsvp.enabled (optional, boolean)– Default: false.– Set to true if you want to enable RSVP functionality for this event.
Example HTTP request
POST https://my.calendarlink.com/api/v1/3f7c05f4-da89-4937-8b0b-f345d3adb01e/eventAuthorization: Bearer NkZBAkSnZPkP9zqDhE5TrTMvvL5lXrXCUPiaKEw1b2486b6cContent-Type: application/json
Body:
{“collection_id”: “4a2a4e56-52ba-4d85-8817-bbb56efc244a”,“title”: “Team Meeting”,“description”: “Quarterly planning session”,“location”: “Conference Room A”,“start”: “2025-12-21 16:00”,“end”: “2025-12-21 18:00”,“timezone”: “Europe/Amsterdam”,“date_format”: “Y-m-d H:i”,“rsvp”: {“enabled”: false}}
Rate limiting
– Maximum of 20 requests per hour per IP address.– If the limit is exceeded, the API returns HTTP 429 (Too Many Requests).– Retry after 3600 seconds.
Input validation
– Dates must match YYYY-MM-DD (e.g. “2025-12-21”).– Times must match HH:MM (e.g. “16:00”).– title cannot be empty after trimming whitespace.– collection_id must be a valid UUID if provided.– description and location are only sent if they have a real value (no empty strings).
Error handling
– 400 Bad Request: validation errors, with details about which field is invalid.– 429 Too Many Requests: rate limit exceeded.– 500 Internal Server Error: CalendarLink API error (message is sanitized).
Response
The API returns the CalendarLink event JSON, including the final add-to-calendar URL (for example: https://calendarlink.com/event/XYZ123). You can show this URL to the user directly, or feed it back into your LLM so the assistant can include a clickable “Add to Calendar” link in its response.