WhenToMeet

基础URL: https://whentomeet.io/api/v1/
OpenAPI规范: https://whentomeet.io/api/openapi.json
认证方式: Authorization: Bearer skYOURAPIKEYHERE

请求/响应格式

请求格式:

• - GET请求: 查询参数 (例如 ?limit=10&offset=0)
• POST请求: 纯JSON主体 (例如 {title: 我的活动})
• 无包装对象 - 直接发送纯JSON

响应格式:

• - 所有响应返回包含ISO 8601日期字符串的纯JSON
• 无信封或包装

日期格式: ISO 8601字符串 (例如 2026-03-14T14:00:00Z)

数据模型

活动对象

• - id: UUID
• title: 字符串 (1-255字符)
• description: 字符串 (可选，最大4096字符)
• status: PLANNING | FINALIZED
• publicUrl: 活动页面的完整URL
• organizerId: UUID
• createdAt: ISO 8601时间戳
• modificationPolicy: EVERYONE | ORGANIZER
• outputCalendarId: UUID (可选，用于将活动最终确定到日历)
• slotCount: 时间段数量

时间段对象

• - id: UUID
• eventId: UUID
• startTime: ISO 8601时间戳
• endTime: ISO 8601时间戳
• timezone: IANA时区标识符 (可选，例如 Europe/Berlin)
• availabilities: 参与者响应数组

创建活动

POST /api/v1/events

bash
curl -X POST https://whentomeet.io/api/v1/events \
-H Authorization: Bearer skYOURAPIKEYHERE \
-H Content-Type: application/json \
-d {
title: 我的活动,
description: 可选描述,
slots: [
{startTime: 2026-03-14T14:00:00Z, endTime: 2026-03-14T16:00:00Z},
{startTime: 2026-03-15T14:00:00Z, endTime: 2026-03-15T16:00:00Z}
],
modificationPolicy: EVERYONE
}

请求字段:

响应:
json
{
id: uuid,
title: 我的活动,
description: 可选描述,
status: PLANNING,
publicUrl: https://whentomeet.io/events/uuid,
slotCount: 2,
createdAt: 2026-03-14T14:00:00Z
}

列出活动

GET /api/v1/events

bash
curl -X GET https://whentomeet.io/api/v1/events?limit=10&offset=0&status=PLANNING \
-H Authorization: Bearer skYOURAPIKEYHERE

查询参数:

响应:
json
[
{
id: uuid,
title: 我的活动,
description: ...,
status: PLANNING,
slotCount: 2,
publicUrl: https://whentomeet.io/events/uuid,
createdAt: 2026-03-14T14:00:00Z
}
]

获取活动详情

GET /api/v1/events/{eventId}

bash
curl -X GET https://whentomeet.io/api/v1/events/{eventId} \
-H Authorization: Bearer skYOURAPIKEYHERE

响应:
json
{
id: uuid,
title: 我的活动,
description: ...,
status: PLANNING,
organizerId: uuid,
createdAt: 2026-03-14T14:00:00Z,
modificationPolicy: EVERYONE,
outputCalendarId: null,
slots: [
{
id: uuid,
eventId: uuid,
startTime: 2026-03-14T14:00:00Z,
endTime: 2026-03-14T16:00:00Z,
availabilities: [
{
id: uuid,
slotId: uuid,
userId: null,
displayName: 张三,
status: available,
user: null
}
]
}
]
}

删除活动

DELETE /api/v1/events/{eventId}

bash
curl -X DELETE https://whentomeet.io/api/v1/events/{eventId} \
-H Authorization: Bearer skYOURAPIKEYHERE

响应:
json
{
success: true
}

其他接口

列出预订

GET /api/v1/bookings

bash
curl -X GET https://whentomeet.io/api/v1/bookings?limit=10&status=confirmed \
-H Authorization: Bearer skYOURAPIKEYHERE

查询参数:

• - limit: 1-100，默认10
• offset: 默认0
• status: confirmed 或 cancelled

列出日历连接

GET /api/v1/calendar/connections

bash
curl -X GET https://whentomeet.io/api/v1/calendar/connections \
-H Authorization: Bearer skYOURAPIKEYHERE

列出所有已连接的日历账户（Google、Microsoft、CalDAV、iCal）。

获取活动统计

GET /api/v1/analytics/events

bash
curl -X GET https://whentomeet.io/api/v1/analytics/events?dateFrom=2026-01-01T00:00:00Z&dateTo=2026-03-13T23:59:59Z \
-H Authorization: Bearer skYOURAPIKEYHERE

查询参数:

• - dateFrom: ISO 8601开始日期（可选，默认为30天前）
• dateTo: ISO 8601结束日期（可选，默认为当前时间）

响应:
json
{
totalEvents: 42,
finalizedEvents: 28,
dateRange: {
from: 2026-01-01T00:00:00Z,
to: 2026-03-13T23:59:59Z
}
}

错误码

错误响应格式:
json
{
error: {
code: NOT_FOUND,
message: 活动未找到或访问被拒绝
}