Agent API quickstart

Help a group choose an option, find a date, or answer a short survey. Guests use a browser link without creating accounts.

Check availability

This guide describes the organizer API in this application version. The organizer release is awaiting public rollout. Check the public release status before directing users to the live beta. MCP is a local stdio adapter in the project source; there is no hosted MCP endpoint or published registry listing.

1. Preview and resolve uncertainty

POST JSON to /api/agent/preview with a description or structured draft. This validates without creating an item. Built-in device dictation can supply text; review names, separators and explicit dates. Ambiguous wording is returned as an issue, not guessed.

{
  "description": "Title: Next workshop date\nDates: 2026-10-10; 2026-10-17"
}

A valid response contains a normalized draft. Show that draft to the organizer and obtain approval before creating. See OpenAPI and examples for choice polls and multi-question surveys.

2. Create with organizer ownership

The organizer signs in and issues an expiring key in Agent access. Store it in the integration host’s secret configuration. POST {"draft": <normalized draft>} to /api/agent/create with Authorization: Bearer <key> and an Idempotency-Key of 8–128 letters, digits, underscores or hyphens.

Keep one key per approved creation intent. After a timeout, retry the identical draft with that same key. Creation saves to the verified account that issued the agent key and queues owner email. An optional ownerEmail must match that account; it cannot transfer ownership.

3. Share the guest link and read status

Return only participantUrl to guests. The response separates creation success from owner-email status: queued is pending; accepted means the provider accepted it, not that it reached the inbox. Outbox is local testing only.

GET /api/agent/status/{kind}/{code} with the owner key reads closed state and response count. It does not expose answers, contacts or management credentials.

Choose the right format

Choice polls: 2–5 alternatives.
Date scheduling: 2–15 distinct dates; date-only values stay calendar dates across time zones.
Short surveys: 1–10 single-choice, multiple-choice, rating or text questions; 200 responses and 90-day lifetime.
Agent limits: five active keys per account, 90-day key expiry, 20 creations per account per hour, 32 KiB request bodies, 8,000-character labeled descriptions. Agent polls use the default theme.

MCP tools

anyofthese_preview and anyofthese_status are read-only. anyofthese_create writes and queues owner email; it is idempotent only with the same key and normalized draft. The adapter uses these HTTP services and requires an explicitly configured application origin. It does not vote, invite guests, read private answers or send arbitrary email.