Developer guide

Why use an API instead of generating ICS yourself?

• No library dependency — no need to pull in an ICS generation library or maintain RFC 5545 compliance.
• Deep links included — the /links endpoint returns Google, Outlook, and Yahoo URLs alongside the ICS download. Building these correctly is non-trivial.
• Edge-hosted — sub-50ms responses globally via Cloudflare Workers. No cold starts.
• Stateless and free — no API key, no rate limits on the main endpoints, no data stored.

JavaScript / TypeScript

async function getCalendarLinks(event: {
  title: string;
  start: string;
  end: string;
  location?: string;
  description?: string;
  reminder?: number;
}) {
  const params = new URLSearchParams();
  for (const [key, value] of Object.entries(event)) {
    if (value !== undefined) params.set(key, String(value));
  }

  const res = await fetch(`https://api.getcal.link/links?${params}`);
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

// Usage
const links = await getCalendarLinks({
  title: 'Sprint Planning',
  start: '2026-03-15T14:00:00Z',
  end: '2026-03-15T15:00:00Z',
  location: 'Zoom',
  reminder: 10,
});

console.log(links.google_url);
console.log(links.ics_url);

Python

import requests
from urllib.parse import urlencode

def get_calendar_links(title, start, end, **kwargs):
    params = {"title": title, "start": start, "end": end, **kwargs}
    resp = requests.get("https://api.getcal.link/links", params=params)
    resp.raise_for_status()
    return resp.json()

links = get_calendar_links(
    title="Sprint Planning",
    start="2026-03-15T14:00:00Z",
    end="2026-03-15T15:00:00Z",
    location="Zoom",
    reminder="10",
)
print(links["google_url"])
print(links["ics_url"])

cURL

# Get JSON links
curl -s "https://api.getcal.link/links?title=Sprint+Planning&start=2026-03-15T14:00:00Z&end=2026-03-15T15:00:00Z" | jq .

# Download ICS file
curl -o event.ics "https://api.getcal.link/event.ics?title=Sprint+Planning&start=2026-03-15T14:00:00Z&end=2026-03-15T15:00:00Z"

Building URLs directly

If you don't need the JSON response, you can construct /event.ics URLs directly and use them as download links. This requires zero API calls — the URL itself is the API:

const icsUrl = new URL('https://api.getcal.link/event.ics');
icsUrl.searchParams.set('title', 'Sprint Planning');
icsUrl.searchParams.set('start', '2026-03-15T14:00:00Z');
icsUrl.searchParams.set('end', '2026-03-15T15:00:00Z');
icsUrl.searchParams.set('reminder', '10');

// Use as a link: icsUrl.toString()
// "https://api.getcal.link/event.ics?title=Sprint+Planning&start=..."

Automation and CI/CD

getcal.link works well in automation pipelines. Common patterns:

• Slack bots — generate calendar links when events are mentioned in channels.
• Webhook handlers — create calendar links when events are created in your system and include them in notifications.
• CI/CD — generate links for upcoming releases or deployment windows and post them to team channels.
• Zapier / Make — use an HTTP request action to call /links and pass the results to downstream steps.

Error handling

The API returns JSON errors with descriptive messages. Always check the response status:

const res = await fetch(url);
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`getcal.link error (${res.status}): ${error}`);
}

See the error reference for all status codes.