English

AI・API連携

ChatGPT・ClaudeなどのAIに、日程調整の作成・回答・確定までを任せるための説明です。

1. MCPサーバーとして接続する(おすすめ)

このサイトは管理者だけが作成できる設定です。参加者としての回答はトークンなしで使えます。作成するには管理者のAPIトークン、またはOAuth(カスタムコネクタの認証)で接続してください。

2. 説明書をAIに読ませる

Markdown: llms.txt · OpenAPI 3.1: openapi.json · JSON Schema: poll.json

# time-of-eve — guide for AI agents

> Scheduling polls (日程調整) that are easy for both humans and AI agents. An organizer proposes candidate time slots; participants mark ○ yes / △ maybe / × no; the server counts, ranks and records the final date. **The server does all counting and ranking — never tally answers yourself.**

Base URL: `https://time-of-eve-staging.haborite.com`
This document: `https://time-of-eve-staging.haborite.com/llms.txt` · MCP: `https://time-of-eve-staging.haborite.com/mcp` · OpenAPI 3.1: `https://time-of-eve-staging.haborite.com/openapi.json` · Poll JSON Schema: `https://time-of-eve-staging.haborite.com/schema/poll.json`
(人間の方へ: このページはAIエージェントが本サービスの使い方を学ぶための説明書です。)

**On this site: only administrators can create polls (API token or OAuth); anyone can answer** · Default time zone: `Asia/Tokyo`

## 0. TL;DR

- Organizer ("make a poll and give me the link"): `create_poll` (MCP) or `POST /api/v1/polls` → give the user **public_url** (send to participants) and **manage_url** (the organizer's private key; keep it).
- Participant ("answer this poll for me"): `get_public_poll` → `submit_response` (or `GET /api/v1/public/{id}` → `POST …/responses`) → give the person their **edit_url** privately.
- Later: `get_results` → report `best_candidate_ids` / `pending_names` → `finalize_poll` when the user decides.

## 1. Access paths — choose honestly

| Path | When | How |
|---|---|---|
| MCP (recommended) | Your client can connect to a remote MCP server (Streamable HTTP) | `https://time-of-eve-staging.haborite.com/mcp`. No token needed for participants. Administrators: header `Authorization: Bearer sch_…` or OAuth. |
| REST API | You can send HTTPS requests | Section 5. |
| Browser | You can operate a browser | Open `https://time-of-eve-staging.haborite.com/new/import`, paste the poll JSON, Validate, tick the confirmation, "作成して公開" (Create and publish). |
| Manual | Plain chat only | Output the poll JSON in one code block and ask the user to paste it at `https://time-of-eve-staging.haborite.com/new/import`. |

Rules:
- Never claim a poll was created or a URL exists unless the server returned it. If a step failed, say which and what the user must do.
- Never ask the user to paste passwords or API tokens into the chat.
- Share only **public_url** with participants. **manage_url** lets anyone edit, finalize or delete the poll; **edit_url** lets anyone change that one person's answer. Never post them publicly or give them to others.
- Answer a poll only for the person who asked you, with their own name and real availability. Never guess availability.

## 2. Preparing candidates

- Confirm title, length, time zone, date range, participants and hard constraints. Ask when unknown; do not invent constraints.
- Write times as **local wall-clock time without offset** — `"2026-12-01T13:00"` — and set `timezone` (IANA, e.g. `Asia/Tokyo`, `America/New_York`). The server derives the UTC offset for each date (DST-safe). If you do include an offset it must be correct for that date, otherwise `timezone_mismatch`.
- Times are on 5-minute boundaries. Typical size: 5–20 candidates; limit 600.
- Two ways to give candidates (can be combined):
  - `candidates`: explicit slots `{"start": "2026-12-01T13:00", "end": "2026-12-01T14:00"}`. With `duration_minutes` set, `end` can be omitted.
  - `candidate_ranges`: windows the server splits into slots of `duration_minutes`: `{"from_date": "2026-12-01", "to_date": "2026-12-05", "weekdays": ["mon","wed","fri"], "start_time": "13:00", "end_time": "17:00"}` (or `date` / `dates`; `step_minutes` for overlapping slots). Past slots are skipped.
- `client_request_id` (optional, recommended): a unique key per poll you intend to create. Resending the identical body returns the same poll (`idempotent_replay: true`) — safe retries. Same key with a different body → `409 idempotency_conflict`.
- Use `dry_run: true` first to see errors, warnings and the expanded candidate list without saving.

## 3. Poll JSON

```json
{
  "title": "研究打合せ 日程調整",
  "description": "オンライン(Zoom)。1時間。",
  "basis": "Organizer free per calendar 11/15; members prefer weekday afternoons.",
  "timezone": "Asia/Tokyo",
  "duration_minutes": 60,
  "candidate_ranges": [
    {"from_date": "2026-12-01", "to_date": "2026-12-04", "weekdays": ["tue", "thu"], "start_time": "13:00", "end_time": "17:00"}
  ],
  "candidates": [{"start": "2026-12-05T10:00"}],
  "response_deadline": "2026-11-28T23:59",
  "allow_maybe": true,
  "show_participant_names": true,
  "participants": [{"display_name": "Aさん", "required": true}, {"display_name": "Bさん"}],
  "client_request_id": "claude-20261116-lab-meeting-1"
}
```

| field | | |
|---|---|---|
| `title` | required | ≤ 200 chars |
| `timezone` | optional | IANA name; default `Asia/Tokyo` |
| `duration_minutes` | optional | 5–1440, multiple of 5. Needed for `candidate_ranges` and for `candidates` without `end` |
| `candidates` / `candidate_ranges` | at least one candidate in total | see section 2 |
| `description` | optional | shown to participants, ≤ 2000 |
| `basis` | optional | organizer-only memo (why these candidates), ≤ 4000. Never shown to participants |
| `response_deadline` | optional | local time or ISO with offset |
| `allow_maybe` | optional | offer △ (default true) |
| `show_participant_names` | optional | show each person's answers by name (default true) |
| `participants` | optional | invitees `{display_name, required?, email?}` (≤ 100); they pick their name when answering. `required: true` → ranking prefers candidates all required people can attend |
| `client_request_id` | optional | idempotency key `[A-Za-z0-9._:-]{1,100}` |

## 4. Statuses and ranking

`draft` (participants cannot see it) → `open` (accepting) → `closed` → `finalized`; any → `cancelled`. An open poll past its deadline behaves as `closed`; `reopen` re-opens it.
Ranking (`best_candidate_ids`): candidates where every required participant answered yes → most yes → fewest no → most maybe. Only candidates with at least one yes are ranked.

## 5. REST API (JSON)

Organizer endpoints authenticate with **one** of: header `X-Manage-Token: <token>` (the last path segment of manage_url), or `Authorization: Bearer sch_…` (administrator API token) / OAuth access token.

| method | path | |
|---|---|---|
| GET | `/api/v1` | service info (who can create, default time zone, links) |
| POST | `/api/v1/polls` | create. Body: poll JSON (+ `"publish": true`, `"dry_run": true`). 201 → `{poll_id, status, public_url, manage_url, version, warnings, idempotent_replay}` |
| GET | `/api/v1/polls/{poll_id}` | details + results summary |
| PATCH | `/api/v1/polls/{poll_id}` | edit: `title`, `description`, `basis`, `response_deadline` (null removes), `show_participant_names`, `duration_minutes`, `add_candidates`, `add_candidate_ranges`, `remove_candidate_ids`, `add_participants`, `set_required` `{"p1": true}`, `version` |
| GET | `/api/v1/polls/{poll_id}/results?view=summary\|full` | tally and ranking |
| POST | `/api/v1/polls/{poll_id}/publish` · `close` · `reopen` (`{"response_deadline"?}`) · `finalize` (`{"candidate_id": "c2", "version"?}`) · `unfinalize` · `cancel` · `rotate-manage-link` | state changes |
| POST | `/api/v1/polls/{poll_id}/participants/{p}/reissue-edit-link` | new edit_url for a participant |
| DELETE | `/api/v1/polls/{poll_id}` | delete permanently |
| GET | `/api/v1/polls` | administrators: list polls |
| GET | `/api/v1/public/{public_id}` | public view (no auth): candidates with ids and tallies, status, deadline, preregistered_pending |
| POST | `/api/v1/public/{public_id}/responses` | answer (no auth): `{"display_name": "…", "answers": {"c1": "yes", "c2": "no"}, "comment": "…"}` or `{"participant_id": "p2", …}` → 201 `{response_id, edit_token, edit_url}` |
| GET / PATCH | `/api/v1/public/{public_id}/responses/{response_id}` | header `X-Edit-Token`. PATCH merges `answers` (null clears one; `"replace_all": true` replaces) and/or `comment` |
| GET | `/api/v1/polls/{poll_id}/export.csv` | CSV |

The public page `https://time-of-eve-staging.haborite.com/p/{public_id}` also answers with Markdown (`/p/{id}.md`, `Accept: text/markdown`) or JSON (`/p/{id}.json`, `Accept: application/json`).

## 6. MCP tools

Participants: `get_public_poll(poll)`, `submit_response(poll, display_name | participant_id, answers, comment?)`, `get_my_response(edit_url)`, `update_my_response(edit_url, answers?, replace_all?, comment?)`.
Organizers (`poll` = manage_url; administrators may pass poll_id): `create_poll(…poll fields, publish?, dry_run?)`, `get_poll`, `get_results(view?)`, `update_poll`, `publish_poll`, `close_poll`, `reopen_poll(response_deadline?)`, `finalize_poll(candidate_id, version?)`, `unfinalize_poll`, `cancel_poll`, `reissue_edit_link(participant_id)`, `delete_poll`. Administrators: `list_polls`.
Also: `get_guide`; resources `time-of-eve://docs/guide`, `time-of-eve://docs/poll-schema.json`, `time-of-eve://polls/{public_id}`; prompts `organize_poll`, `answer_poll`.

## 7. Errors

`{"error": {"code", "field", "message", "hint"}, "errors": [...], "warnings": [...], "docs": "https://time-of-eve-staging.haborite.com/llms.txt"}`. Fix every entry of `errors` (`field` says where, `hint` says how) and retry. Common codes:
`validation_failed` (see errors[]), `invalid_datetime`, `timezone_mismatch` (drop the offset), `nonexistent_local_time` (DST gap), `missing_end`, `duration_mismatch`, `range_needs_duration`, `no_candidates`, `too_many_candidates`, `idempotency_conflict`, `version_conflict` (re-read and retry), `invalid_state`, `not_accepting`, `use_participant_id` (the name is an invitee: send participant_id), `already_responded` (use the edit_url), `invalid_manage_token`, `invalid_edit_token`, `creation_disabled`, `rate_limited` (wait a minute).
Warnings (`candidate_in_past`, `candidate_overlap`, `deadline_after_candidate`, `range_empty`, `unknown_field`, …) do not block.