Get Calendar agenda - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

Conditional availability: these routes require CALENDAR_INTEGRATION_ENABLED=true; otherwise they return 404. Use a signed-in user session or a developer API key with the listed Calendar scope. Access uses the key owner’s own connected personal calendar in the current workspace. Calendar OAuth consent is separate from email consent. Credentials are never returned.

Empty filtered pages can still have has_more=true. Continue the complete cursor chain from the first page to exhaustion before claiming no matching event exists. Each query covers at most 90 days, including historical periods; the bound is per query. Coverage is limited to this account, range, and filters. Calendar evidence establishes a scheduled meeting and does not establish that a call occurred. To expand one compact match, get its agenda event details.

Command Center reads additionally respect CALENDAR_AGENT_READ_ENABLED; agent writes require CALENDAR_AGENT_ENABLED=true. HTTP and CLI availability do not by themselves prove that the harness adapter is enabled. Use capability discovery for the deployed surface.

Path parameters

providerrequired
string
google or microsoft; use a connected account from the connections response.

Name	Type	Description
providerrequired	string	google or microsoft; use a connected account from the connections response.

Query parameters

startrequired
string (date-time)
Inclusive start with a UTC offset. The requested range must be positive and at most 90 days.
endrequired
string (date-time)
Exclusive end with a UTC offset, after start.
query · optional
string
Text search, 1–200 characters. Google searches at the provider; Microsoft filters each retrieved page case-insensitively.
attendee · optional
string (email)
Filter by an exact attendee email.
attendee_domain · optional
string
Exact attendee domain, for example example.com; omit @ and URL prefixes.
page_size · optional
integer
1–100; the HTTP route defaults to 100.
cursor · optional
string
Opaque next_cursor from the prior page. Preserve the same account, range, filters, and projection.
projection · optional
string
compact or full; the HTTP route defaults to full. Compact omits event descriptions.
include_crm_context · optional
boolean
Optional organization CRM context; default false.

Name	Type	Description
startrequired	string (date-time)	Inclusive start with a UTC offset. The requested range must be positive and at most 90 days.
endrequired	string (date-time)	Exclusive end with a UTC offset, after start.
query	string	Text search, 1–200 characters. Google searches at the provider; Microsoft filters each retrieved page case-insensitively.
attendee	string (email)	Filter by an exact attendee email.
attendee_domain	string	Exact attendee domain, for example example.com; omit @ and URL prefixes.
page_size	integer	1–100; the HTTP route defaults to 100.
cursor	string	Opaque next_cursor from the prior page. Preserve the same account, range, filters, and projection.
projection	string	compact or full; the HTTP route defaults to full. Compact omits event descriptions.
include_crm_context	boolean	Optional organization CRM context; default false.

Errors

Status	Meaning
400	Invalid range or provider state, reconnect required, CRM match missing, or event not editable.
401	Authentication required.
403	The key lacks the required Calendar scope.
404	Calendar is disabled, the connection is unavailable, or the event is not found.
409	Event version changed; read and review again.
422	Invalid request fields.
502	Calendar provider request failed.

Example

bash

curl -X GET "https://app.autotouch.ai/api/calendar/google/agenda" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY"

Response example

json

{
  "events": [
    {
      "id": "event_example",
      "provider": "google",
      "title": "Account review",
      "description": "Review next steps.",
      "start": {
        "dateTime": "2026-11-02T15:00:00Z"
      },
      "end": {
        "dateTime": "2026-11-02T15:30:00Z"
      },
      "attendees": [
        "alex@example.com"
      ],
      "url": "https://calendar.google.com/calendar/event?eid=example",
      "conference_url": null,
      "etag": "event-version-example",
      "series_id": null,
      "organizer": "sdr@example.com",
      "status": "confirmed"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "calendar": "primary",
  "provider": "google",
  "start": "2026-11-02T00:00:00+00:00",
  "end": "2026-11-03T00:00:00+00:00",
  "projection": "full",
  "returned_count": 1,
  "coverage": {
    "scope": "connected_primary_calendar",
    "from_start": true,
    "exhausted": true,
    "complete": true,
    "start": "2026-11-02T00:00:00+00:00",
    "end": "2026-11-03T00:00:00+00:00",
    "query": null,
    "attendee": null,
    "attendee_domain": null,
    "scanned_count": 1,
    "search_mode": "provider_text_search"
  }
}