{"openapi":"3.1.0","info":{"title":"time-of-eve API","version":"1.0.0","description":"Scheduling polls for humans and AI agents. Guide: https://time-of-eve-staging.haborite.com/llms.txt. Organizer endpoints: X-Manage-Token (from manage_url) or administrator bearer token. Participant endpoints need no auth."},"servers":[{"url":"https://time-of-eve-staging.haborite.com/api/v1"}],"components":{"securitySchemes":{"manageToken":{"type":"apiKey","in":"header","name":"X-Manage-Token","description":"Last path segment of manage_url"},"bearer":{"type":"http","scheme":"bearer","description":"Administrator API token (sch_…) or OAuth access token"},"editToken":{"type":"apiKey","in":"header","name":"X-Edit-Token"}},"schemas":{"Poll":{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"time-of-eve poll","description":"Body of POST /api/v1/polls and arguments of the MCP tool create_poll. Times: local \"YYYY-MM-DDTHH:MM\" in `timezone` (or ISO 8601 with the correct offset).","type":"object","properties":{"title":{"type":"string","description":"Poll title"},"description":{"description":"Shown to participants (format, place, notes). Max 2000.","type":"string"},"basis":{"description":"Organizer-only memo: why these candidates (sources, constraints). Never shown to participants.","type":"string"},"timezone":{"description":"IANA time zone, e.g. Asia/Tokyo. Defaults to the site's default time zone.","type":"string"},"duration_minutes":{"description":"Length of each candidate in minutes (5–1440).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"candidates":{"description":"Explicit candidate slots.","type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"Local time in the poll's timezone \"2026-12-01T13:00\" (recommended), or ISO 8601 with offset \"2026-12-01T13:00:00+09:00\"."},"end":{"description":"Omit when duration_minutes is set: end = start + duration_minutes.","type":"string"},"allow_duration_mismatch":{"description":"Set true if this candidate's length intentionally differs from duration_minutes.","type":"boolean"}},"required":["start"]}},"candidate_ranges":{"description":"Windows expanded into slots by the server (needs duration_minutes).","type":"array","items":{"type":"object","properties":{"date":{"description":"One date YYYY-MM-DD","type":"string"},"dates":{"description":"Several dates YYYY-MM-DD","type":"array","items":{"type":"string"}},"from_date":{"description":"First date of a period YYYY-MM-DD (with to_date)","type":"string"},"to_date":{"description":"Last date of a period YYYY-MM-DD (inclusive)","type":"string"},"weekdays":{"description":"Keep only these weekdays, e.g. [\"mon\",\"wed\"]","type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start_time":{"type":"string","description":"Window start HH:MM (local)"},"end_time":{"type":"string","description":"Window end HH:MM (local, 24:00 allowed)"},"step_minutes":{"description":"Start a slot every N minutes (default duration_minutes = back-to-back slots)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["start_time","end_time"],"description":"A time window split into slots of duration_minutes, e.g. weekdays 13:00–17:00 of a week."}},"response_deadline":{"description":"Answers close after this time (local or with offset).","type":["string","null"]},"allow_maybe":{"description":"Offer △ maybe in addition to ○ yes / × no (default true).","type":"boolean"},"show_participant_names":{"description":"Show each participant's answers by name on the public page (default true).","type":"boolean"},"participants":{"description":"People invited in advance (they pick their name when answering).","type":"array","items":{"type":"object","properties":{"display_name":{"type":"string","description":"Name shown in the poll"},"email":{"description":"Never shown publicly","type":"string"},"required":{"description":"Must attend: ranking prefers candidates all required people can attend","type":"boolean"}},"required":["display_name"]}},"client_request_id":{"description":"Idempotency key (1–100 of A-Z a-z 0-9 . _ : -). Resending the same body returns the same poll.","type":"string"},"publish":{"type":"boolean"},"dry_run":{"type":"boolean"}},"required":["title"]},"Patch":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"basis":{"type":"string"},"response_deadline":{"description":"New deadline (local or with offset), null removes it","type":["string","null"]},"show_participant_names":{"type":"boolean"},"duration_minutes":{"description":"Default length for added candidates","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"add_candidates":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"Local time in the poll's timezone \"2026-12-01T13:00\" (recommended), or ISO 8601 with offset \"2026-12-01T13:00:00+09:00\"."},"end":{"description":"Omit when duration_minutes is set: end = start + duration_minutes.","type":"string"},"allow_duration_mismatch":{"description":"Set true if this candidate's length intentionally differs from duration_minutes.","type":"boolean"}},"required":["start"]}},"add_candidate_ranges":{"type":"array","items":{"type":"object","properties":{"date":{"description":"One date YYYY-MM-DD","type":"string"},"dates":{"description":"Several dates YYYY-MM-DD","type":"array","items":{"type":"string"}},"from_date":{"description":"First date of a period YYYY-MM-DD (with to_date)","type":"string"},"to_date":{"description":"Last date of a period YYYY-MM-DD (inclusive)","type":"string"},"weekdays":{"description":"Keep only these weekdays, e.g. [\"mon\",\"wed\"]","type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start_time":{"type":"string","description":"Window start HH:MM (local)"},"end_time":{"type":"string","description":"Window end HH:MM (local, 24:00 allowed)"},"step_minutes":{"description":"Start a slot every N minutes (default duration_minutes = back-to-back slots)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["start_time","end_time"],"description":"A time window split into slots of duration_minutes, e.g. weekdays 13:00–17:00 of a week."}},"remove_candidate_ids":{"description":"e.g. [\"c3\"]; existing answers are kept but ignored","type":"array","items":{"type":"string"}},"add_participants":{"type":"array","items":{"type":"object","properties":{"display_name":{"type":"string","description":"Name shown in the poll"},"email":{"description":"Never shown publicly","type":"string"},"required":{"description":"Must attend: ranking prefers candidates all required people can attend","type":"boolean"}},"required":["display_name"]}},"set_required":{"description":"{\"p1\": true}","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"version":{"description":"version from your last read; fails with version_conflict if the poll changed since","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"Response":{"type":"object","properties":{"participant_id":{"description":"Invited participant's id (\"p2\") from preregistered_pending; instead of display_name","type":"string"},"display_name":{"description":"The participant's own name","type":"string"},"answers":{"description":"Candidate id → \"yes\" | \"maybe\" | \"no\" (null or omitted = unanswered), e.g. {\"c1\":\"yes\",\"c2\":\"no\"}","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","enum":["yes","maybe","no"]},{"type":"null"}]}},"slots":{"description":"Timeline marks used by the web UI (alternative to answers)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","enum":["yes","maybe","no"]},{"type":"null"}]}},"comment":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}}},"errors":{"type":"array","items":{"type":"object"}},"warnings":{"type":"array","items":{"type":"object"}},"docs":{"type":"string"}}}}},"paths":{"/polls":{"post":{"operationId":"createPoll","summary":"Create a poll (publish: true to open it; dry_run: true to validate only). Returns public_url and manage_url.","responses":{"200":{"description":"Idempotent replay or dry run","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{},{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Poll"}}}}},"get":{"operationId":"listPolls","summary":"List polls (administrators)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/polls/{poll_id}":{"get":{"operationId":"getPoll","summary":"Poll details and results summary","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}]},"patch":{"operationId":"updatePoll","summary":"Edit a poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Patch"}}}}},"delete":{"operationId":"deletePoll","summary":"Delete a poll permanently","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}]}},"/polls/{poll_id}/results":{"get":{"operationId":"getResults","summary":"Tally and ranking","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"},{"name":"view","in":"query","schema":{"enum":["summary","full"]}}],"security":[{"manageToken":[]},{"bearer":[]}]}},"/polls/{poll_id}/publish":{"post":{"operationId":"publishPoll","summary":"publish the poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/polls/{poll_id}/close":{"post":{"operationId":"closePoll","summary":"close the poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/polls/{poll_id}/reopen":{"post":{"operationId":"reopenPoll","summary":"Reopen: {response_deadline?}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"response_deadline":{"type":"string"}}}}}}}},"/polls/{poll_id}/finalize":{"post":{"operationId":"finalizePoll","summary":"Fix the date: {candidate_id, version?}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["candidate_id"],"properties":{"candidate_id":{"type":"string"},"version":{"type":"integer"}}}}}}}},"/polls/{poll_id}/unfinalize":{"post":{"operationId":"unfinalizePoll","summary":"unfinalize the poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/polls/{poll_id}/cancel":{"post":{"operationId":"cancelPoll","summary":"cancel the poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/polls/{poll_id}/rotate-manage-link":{"post":{"operationId":"rotateManageLinkPoll","summary":"rotate-manage-link the poll","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"}],"security":[{"manageToken":[]},{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/polls/{poll_id}/participants/{participant_id}/reissue-edit-link":{"post":{"operationId":"reissueEditLink","summary":"New edit_url for a participant (old one stops working)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"poll_id","in":"path","required":true,"schema":{"type":"string"},"description":"poll_id (26 characters) from create"},{"name":"participant_id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]},{"bearer":[]}]}},"/public/{public_id}":{"get":{"operationId":"getPublicPoll","summary":"Public view of a poll (no auth)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{}]}},"/public/{public_id}/responses":{"post":{"operationId":"submitResponse","summary":"Answer a poll (no auth). Returns edit_url (secret).","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}}}},"/public/{public_id}/responses/{response_id}":{"get":{"operationId":"getMyResponse","summary":"Read own answer","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"response_id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"editToken":[]}]},"patch":{"operationId":"updateMyResponse","summary":"Change own answer (answers merge; null clears; replace_all)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"response_id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"editToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}}}}}}