composio-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Calendar via Composio

Critical: CREATE vs UPDATE Parameters

重要提示：CREATE与UPDATE参数差异

This is the most common bug. CREATE and UPDATE use different parameters for event duration:

Action Duration Method Example

Action	Duration Method	Example
`GOOGLECALENDAR_CREATE_EVENT`	`event_duration_hour` + `event_duration_minutes`	`{"event_duration_hour": 2, "event_duration_minutes": 0}`
`GOOGLECALENDAR_UPDATE_EVENT`	`end_datetime`	`{"end_datetime": "2026-02-24T21:00:00"}`
`GOOGLECALENDAR_PATCH_EVENT`	`end_datetime`	`{"end_datetime": "2026-02-24T21:00:00"}`

GOOGLECALENDAR_CREATE_EVENT

event_duration_hour

event_duration_minutes

{"event_duration_hour": 2, "event_duration_minutes": 0}

GOOGLECALENDAR_UPDATE_EVENT

end_datetime

{"end_datetime": "2026-02-24T21:00:00"}

GOOGLECALENDAR_PATCH_EVENT

end_datetime

{"end_datetime": "2026-02-24T21:00:00"}

If you pass
end_datetime
to CREATE, it is IGNORED and the event defaults to 30 minutes.

这是最常见的问题。 CREATE和UPDATE操作使用不同的参数来设置活动时长：

操作时长设置方式示例

操作	时长设置方式	示例
`GOOGLECALENDAR_CREATE_EVENT`	`event_duration_hour` + `event_duration_minutes`	`{"event_duration_hour": 2, "event_duration_minutes": 0}`
`GOOGLECALENDAR_UPDATE_EVENT`	`end_datetime`	`{"end_datetime": "2026-02-24T21:00:00"}`
`GOOGLECALENDAR_PATCH_EVENT`	`end_datetime`	`{"end_datetime": "2026-02-24T21:00:00"}`

GOOGLECALENDAR_CREATE_EVENT

event_duration_hour

event_duration_minutes

{"event_duration_hour": 2, "event_duration_minutes": 0}

GOOGLECALENDAR_UPDATE_EVENT

end_datetime

{"end_datetime": "2026-02-24T21:00:00"}

GOOGLECALENDAR_PATCH_EVENT

end_datetime

{"end_datetime": "2026-02-24T21:00:00"}

如果在CREATE操作中传入
end_datetime
参数，该参数会被忽略，活动时长将默认设为30分钟。

Environment

环境变量

bash

COMPOSIO_API_KEY      # API key
COMPOSIO_USER_ID      # Entity ID (required for all requests)
COMPOSIO_CONNECTIONS  # JSON with .googlecalendar connection ID

bash

COMPOSIO_API_KEY      # API密钥
COMPOSIO_USER_ID      # 实体ID（所有请求必填）
COMPOSIO_CONNECTIONS  # 包含.googlecalendar连接ID的JSON数据

Core Pattern

核心调用模式

bash

CONNECTION_ID=$(echo $COMPOSIO_CONNECTIONS | jq -r '.googlecalendar')

curl -s "https://backend.composio.dev/api/v3/tools/execute/ACTION_NAME" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {}
  }' | jq '.data'

bash

CONNECTION_ID=$(echo $COMPOSIO_CONNECTIONS | jq -r '.googlecalendar')

curl -s "https://backend.composio.dev/api/v3/tools/execute/ACTION_NAME" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {}
  }' | jq '.data'

Creating Events

创建活动

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_CREATE_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "title": "Work Block: API Docs",
      "start_datetime": "2026-02-24T09:00:00",
      "event_duration_hour": 2,
      "event_duration_minutes": 0,
      "timezone": "America/Los_Angeles",
      "description": "Focus time for API documentation",
      "calendar_id": "primary"
    }
  }' | jq

Duration rules:

```
event_duration_minutes
```
: 0-59 ONLY. Never use 60+.

For 90 minutes:

event_duration_hour: 1, event_duration_minutes: 30

For 2 hours:

event_duration_hour: 2, event_duration_minutes: 0

Defaults:

```
calendar_id
```
: "primary" if omitted
```
create_meeting_room
```
: true (adds Google Meet link)
```
timezone
```
: UTC if omitted

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_CREATE_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "title": "Work Block: API Docs",
      "start_datetime": "2026-02-24T09:00:00",
      "event_duration_hour": 2,
      "event_duration_minutes": 0,
      "timezone": "America/Los_Angeles",
      "description": "Focus time for API documentation",
      "calendar_id": "primary"
    }
  }' | jq

时长规则：

```
event_duration_minutes
```
：只能设置0-59之间的值，请勿设置60或以上。

若要设置90分钟：

event_duration_hour: 1, event_duration_minutes: 30

若要设置2小时：

event_duration_hour: 2, event_duration_minutes: 0

默认值：

```
calendar_id
```
：如果省略则默认使用"primary"
```
create_meeting_room
```
：默认true（自动添加Google Meet链接）
```
timezone
```
：如果省略则默认使用UTC时区

Finding Events

查找活动

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_FIND_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "text_query": "API Docs",
      "time_min": "2026-02-24T00:00:00Z",
      "time_max": "2026-02-25T00:00:00Z",
      "calendar_id": "primary"
    }
  }' | jq

Use

GOOGLECALENDAR_FIND_EVENT

to get

event_id

before updating or deleting.

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_FIND_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "text_query": "API Docs",
      "time_min": "2026-02-24T00:00:00Z",
      "time_max": "2026-02-25T00:00:00Z",
      "calendar_id": "primary"
    }
  }' | jq

在更新或删除活动前，请使用

GOOGLECALENDAR_FIND_EVENT

获取

event_id

。

Updating Events

更新活动

Use PATCH for partial updates (preferred), UPDATE for full replacement:

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_PATCH_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "event_id": "abc123",
      "calendar_id": "primary",
      "end_datetime": "2026-02-24T11:00:00"
    }
  }' | jq

Note: UPDATE replaces the entire event; unspecified fields may be cleared.

推荐使用PATCH进行部分更新，UPDATE用于完全替换活动信息：

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_PATCH_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "event_id": "abc123",
      "calendar_id": "primary",
      "end_datetime": "2026-02-24T11:00:00"
    }
  }' | jq

注意： UPDATE操作会替换整个活动信息，未指定的字段可能会被清空。

Deleting Events

删除活动

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_DELETE_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "event_id": "abc123",
      "calendar_id": "primary"
    }
  }' | jq

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_DELETE_EVENT" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "event_id": "abc123",
      "calendar_id": "primary"
    }
  }' | jq

Finding Free Slots

查找空闲时段

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_FREE_BUSY" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "time_min": "2026-02-24T09:00:00Z",
      "time_max": "2026-02-24T18:00:00Z"
    }
  }' | jq

bash

curl -s "https://backend.composio.dev/api/v3/tools/execute/GOOGLECALENDAR_FREE_BUSY" \
  -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "'$CONNECTION_ID'",
    "entity_id": "'$COMPOSIO_USER_ID'",
    "arguments": {
      "time_min": "2026-02-24T09:00:00Z",
      "time_max": "2026-02-24T18:00:00Z"
    }
  }' | jq

Common Patterns

常见使用场景

Scheduling Multiple Work Blocks

安排多个工作时段

When creating multiple events in sequence:

Calculate each
```
start_datetime
```
explicitly

Use

event_duration_hour

event_duration_minutes

for each

Account for breaks between blocks

Example: 3 two-hour blocks with 30-min breaks:

Block 1: 9:00-11:00 (
```
start: 09:00, duration: 2h
```
)
Block 2: 11:30-13:30 (
```
start: 11:30, duration: 2h
```
)
Block 3: 14:00-16:00 (
```
start: 14:00, duration: 2h
```
)

当需要连续创建多个活动时：

明确计算每个活动的
```
start_datetime
```

为每个活动设置

event_duration_hour

event_duration_minutes

参数

考虑时段之间的休息时间

示例：3个2小时的工作时段，中间间隔30分钟休息：

时段1：9:00-11:00（
```
start: 09:00, duration: 2h
```
）
时段2：11:30-13:30（
```
start: 11:30, duration: 2h
```
）
时段3：14:00-16:00（
```
start: 14:00, duration: 2h
```
）

Fixing Duration After Creation

创建后修正活动时长

If events were created with wrong duration:

Find events:
```
GOOGLECALENDAR_FIND_EVENT
```
Patch each:
```
GOOGLECALENDAR_PATCH_EVENT
```
with correct
```
end_datetime
```

如果活动创建时设置了错误的时长：

使用
```
GOOGLECALENDAR_FIND_EVENT
```
查找活动
使用
```
GOOGLECALENDAR_PATCH_EVENT
```
并传入正确的
```
end_datetime
```
参数来修正

Datetime Formats

日期时间格式

ISO 8601:
```
YYYY-MM-DDTHH:MM:SS
```
(e.g.,
```
2026-02-24T09:00:00
```
)
With timezone:
```
2026-02-24T09:00:00-08:00
```
or use
```
timezone
```
param
Natural language NOT supported: "tomorrow", "next Monday" will be rejected

ISO 8601格式：
```
YYYY-MM-DDTHH:MM:SS
```
（例如：
```
2026-02-24T09:00:00
```
）
带时区的格式：
```
2026-02-24T09:00:00-08:00
```
，或使用
```
timezone
```
参数指定时区
不支持自然语言：如"tomorrow"、"next Monday"这类表述会被拒绝

All Actions

所有操作

See references/actions.md for complete API reference.

完整的API参考请查看references/actions.md。

Discover Actions

查看所有操作

bash

curl -s "https://backend.composio.dev/api/v2/actions?apps=googlecalendar" \
  -H "x-api-key: $COMPOSIO_API_KEY" | jq '.items[] | {name, description}'

bash

curl -s "https://backend.composio.dev/api/v2/actions?apps=googlecalendar" \
  -H "x-api-key: $COMPOSIO_API_KEY" | jq '.items[] | {name, description}'