# LinkyCal

> Headless forms, scheduling, contacts, workflows, aggregate funnel analytics, and embeddable widgets. LinkyCal is API-first and includes a project-scoped MCP server an AI agent can drive.

Base URL: https://linkycal.com
API docs: https://linkycal.com/docs
OpenAPI 3.1: https://linkycal.com/openapi.json

## Authentication

Protected project management and MCP use a project-scoped API key. Create one under MCP & APIs and send:

    Authorization: Bearer lc_live_...

The key can reach exactly one project and must be used only from a trusted server or local agent. Visitor form, booking, availability, widget, and telemetry endpoints are anonymous and rate-limited.

Send either a dashboard session or an API key, never both. Ambiguous credentials return 400; invalid bearer credentials return 401 and never fall back to a session.

## Protected management REST API

Base path: https://linkycal.com/api/projects/:projectId

API-key-enabled domains:
- Projects and entitlements.
- Event types, schedules, availability rules, and calendar selections.
- Booking management and linked form responses.
- Forms, steps, fields, responses, and private files.
- Contacts, tags, saved views, pipeline stages, and activity.
- Workflows, runs, triggers, and tests.
- Recent activity and aggregate analytics.
- Project-owned files and calendar enumeration.

Project creation/deletion, membership, API-key management, teams, billing, onboarding, and OAuth connection lifecycle remain dashboard-only.

## Detailed analytics REST API

Detailed reports and provider configuration require Pro or Business. The Worker enforces this entitlement for dashboard sessions, API keys, MCP, provider mutation, and provider publication.

- GET /api/projects/:projectId/analytics/filters — List analytics filters and project resources. Pro or Business required. Returns project-owned event types/forms plus observed UTM, source, and device values.
- GET /api/projects/:projectId/analytics/overview — Get analytics overview. Pro or Business required. Returns aggregate traffic and conversion totals without visitor histories.
- GET /api/projects/:projectId/analytics/bookings — Get booking funnel analytics. Pro or Business required. Select an event type for unique-journey stage continuation, drop-offs, dates, availability, offered times, selected times, and safe failures.
- GET /api/projects/:projectId/analytics/forms — Get form funnel analytics. Pro or Business required. Select a form for unique-journey question/step continuation, skips, drop-offs, and safe validation failures.
- GET /api/projects/:projectId/analytics/integrations — List analytics integrations. Pro or Business required. Returns normalized public GA4, Meta Pixel, and PostHog configuration.
- PUT /api/projects/:projectId/analytics/integrations/:provider — Configure an analytics integration. Pro or Business required. Provider is ga4, meta_pixel, or posthog. Raw scripts, script URLs, secrets, and arbitrary PostHog hosts are rejected.

Report filters:
- period: 7d, 30d, 90d, or custom.
- start and end: inclusive YYYY-MM-DD values accepted together only for custom.
- resourceSlug: select one project-owned event type or form for exact stages.
- utmSource, utmMedium, utmCampaign.
- source: direct or widget.
- deviceType: mobile, tablet, or desktop.

Booking reports preserve high-level totals and add unique-journey stages, continuation and drop-off rates, selected dates, availability outcomes, literal local offered times, selected times, attached-form stages, and safe submit failure categories.

Form reports preserve high-level totals and add the rendered statement/question/group/step sequence, unique-journey continuation and drop-offs, conditional skips, safe validation categories, and submit failures. Focused forms continue to persist every step response independently of analytics delivery.

Aggregate analytics never contain names, emails, raw answers, journey IDs, IP addresses, or raw errors. Provider payloads also exclude labels and visitor histories. Detailed results expose the first-ingestion boundary so older traffic is not presented as zero detailed activity.

Provider configuration accepts structured public identifiers only:
- GA4: measurementId matching a G- identifier.
- Meta Pixel: numeric pixelId.
- PostHog: projectKey plus host us or eu.

Raw JavaScript, GTM containers, script URLs, secrets, and arbitrary provider hosts are rejected.

Anonymous telemetry uses POST /api/v1/t. It accepts one canonical event or an array of 1–20 events, is rate-limited to 120 requests/minute/IP, ignores unknown projects, and returns 204.

## MCP server

Endpoint: https://linkycal.com/api/mcp
Transport: Streamable HTTP
Auth: project API key as a Bearer token

Every tool is hard-scoped to the API key project, so no tool accepts projectId.

The server exposes 40 tools:
- Bookings: list_bookings, get_booking, get_available_slots, create_booking, cancel_booking, confirm_booking, decline_booking — Read and manage bookings and public availability.
- Event Types: list_event_types, get_event_type, create_event_type, update_event_type — Define bookable meeting types.
- Schedules: list_schedules, get_schedule — Inspect the working hours behind event types.
- Contacts: list_contacts, get_contact, create_contact, update_contact, set_contact_next_action, complete_contact_next_action, delete_contact, get_contact_activity — Manage CRM records and their activity.
- Tags: list_contact_tags, get_contact_tag, create_contact_tag, update_contact_tag, delete_contact_tag, add_tag_to_contact, remove_tag_from_contact — Manage tags and contact assignments.
- Forms: list_forms, get_form, create_form, update_form, list_form_responses — Build forms and inspect aggregate submissions.
- Workflows: list_workflows, get_workflow — Inspect workflows; writes remain REST/dashboard-only.
- Analytics: get_analytics_overview, get_booking_funnel_analytics, get_form_funnel_analytics, list_analytics_integrations, configure_analytics_integration — Read aggregate funnels and configure validated GA4, Meta Pixel, and PostHog public identifiers.

Analytics MCP details:
- get_analytics_overview: common period, custom dates, UTM, source, and device inputs; returns aggregate totals/time series.
- get_booking_funnel_analytics: optional project-owned eventTypeId for exact booking stages and context.
- get_form_funnel_analytics: optional project-owned formId for rendered form stages and skips.
- list_analytics_integrations: returns normalized GA4, Meta Pixel, and PostHog public configuration.
- configure_analytics_integration: provider, enabled, provider-specific public identifier, and allowlisted PostHog host.

Analytics MCP outputs are aggregate and use the same actions, ownership checks, validation, and Pro/Business gating as REST.

## Public forms API

Start a response:

    POST /api/v1/forms/:projectSlug/:formSlug/responses

Submit each step in order:

    PATCH /api/v1/forms/:projectSlug/:formSlug/responses/:responseId/steps/:stepIndex

Body fields is an array of fieldId/value entries. Set complete=true on the final visible step. File fields first upload with:

    POST /api/v1/forms/:projectSlug/:formSlug/responses/:responseId/uploads

Private response file download requires an API key:

    GET /api/v1/forms/:projectSlug/:formSlug/responses/:responseId/files/:valueId

The legacy /api/public form routes remain available for compatibility; new integrations should use /api/v1.

## Public booking API

Check availability:

    GET /api/v1/availability/:projectSlug?date=YYYY-MM-DD&eventTypeSlug=slug&timezone=IANA

Create a booking:

    POST /api/v1/bookings

Required JSON fields are projectSlug, eventTypeSlug, startTime, name, email, and timezone. Optional notes and formFields hold intake details. Success can trigger confirmation email, Google Calendar delivery, and workflows.

## Widgets

Booking and form widgets are zero-dependency IIFE bundles:

    <script src="https://cdn.linkycal.com/widgets/booking.js"></script>
    <script src="https://cdn.linkycal.com/widgets/form.js"></script>

Initialize LinkyCal.booking with projectSlug, container, and optional eventTypeSlug. Initialize LinkyCal.form with projectSlug, formSlug, and container. Widget journeys are attributed as source=widget and share one resource-scoped anonymous journey with their iframe.

## Workflows

Triggers include form and booking lifecycle, contacts, tags, schedules, manual, and scheduled runs. Actions include email, AI research, tags, waits, conditions, webhooks, and contact updates. Webhook/email/calendar/provider failure is isolated according to each domain's delivery contract.

## Rate limits

- Anonymous telemetry: 120/min/IP.
- Availability: 60/min/IP.
- Booking creation: 10/min/IP.
- Form response creation: 30/min/IP.
- Form step submission: 60/min/IP.
- File upload: 30/min/IP.

## Errors

Errors use JSON with error and an optional stable code. Common statuses: 400 validation or ambiguous credentials, 401 invalid key, 403 project/plan denial, 404 not found, 429 rate limited, and 500 server error.