{"openapi":"3.1.0","info":{"title":"AnyOfThese organizer agent API","version":"1.0.0","description":"Release candidate contract; live organizer rollout pending. Preview does not create resources. Creation requires an active verified owner account, owner-issued agent key, and a reviewed draft. Never share management credentials. API acceptance of owner email does not prove inbox delivery."},"servers":[{"url":"https://beta.anyofthese.com","description":"This application instance"}],"paths":{"/api/agent/preview":{"post":{"operationId":"preview","summary":"Validate without creating an item","security":[],"description":"Supply description OR draft. If both are supplied the server uses description. Descriptions use labeled lines and explicit dates; ambiguous prose produces 422. Rate limited by client IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"description":{"type":"string","maxLength":8000}},"required":["description"]},{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/Draft"}},"required":["draft"]}]},"examples":{"choice":{"value":{"description":"Title: Next club outing\nChoices: Museum; Picnic; Bowling"}},"dates":{"value":{"description":"Title: Next workshop date\nDates: 2026-10-10; 2026-10-17"}},"survey":{"value":{"draft":{"kind":"survey","data":{"title":"Workshop feedback","mode":"anonymous","activity":"Craft workshop","occurrence":"October session","questions":[{"id":"useful","type":"rating","title":"How useful was the workshop?","required":true,"scale":5},{"id":"next","type":"text","title":"What should we try next?","required":false}]}}}}}}}},"responses":{"200":{"description":"Valid normalized preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unresolved draft; review issues before creating","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/create":{"post":{"operationId":"create","summary":"Create a reviewed draft and queue owner email","security":[{"AgentKey":[]}],"description":"User approval should precede this call. Saves to the verified key owner. At most 20 creations per account per hour. Idempotency is account-scoped for 90 days; retry the identical normalized draft and key after uncertainty. Optional ownerEmail must match the verified key owner, never transfers ownership.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/Draft"},"ownerEmail":{"type":"string","format":"email"}},"required":["draft"]}}}},"responses":{"200":{"description":"Created or replayed, with participant URL and owner-mail status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Created"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner/account access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Item or route unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Same idempotency key, different draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Original creation expired or deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/status/{kind}/{code}":{"get":{"operationId":"status","summary":"Read owner-only aggregate status","security":[{"AgentKey":[]}],"parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["poll","survey"]}},{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"No individual answers or private management URLs","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["poll","survey"]},"code":{"type":"string"},"closed":{"type":"boolean"},"responseCount":{"type":"integer","minimum":0}},"required":["kind","code","closed","responseCount"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Owner/account access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Item or route unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Original creation expired or deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"AgentKey":{"type":"http","scheme":"bearer","description":"ak_ followed by 64 lowercase hex characters. Issue/revoke through signed-in /agent-access. 90-day expiry, five active keys per account. Never put keys in URLs or drafts."}},"schemas":{"Option":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100},"detail":{"type":["string","null"],"maxLength":150,"description":"Date-only YYYY-MM-DD or a supported scheduling timestamp; use preview for semantic validation."},"endDetail":{"type":["string","null"]},"placeId":{"type":["string","null"]}},"required":["label"]},"Question":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,32}$","description":"Distinct; reserved prototype identifiers are rejected."},"type":{"type":"string","enum":["single","multiple","rating","text"]},"title":{"type":"string","minLength":1,"maxLength":160},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":8},"scale":{"type":"integer","enum":[5,7,10]}},"required":["id","type","title","required"],"allOf":[{"if":{"properties":{"type":{"enum":["single","multiple"]}}},"then":{"required":["options"],"properties":{"options":{"minItems":2}}}},{"if":{"properties":{"type":{"const":"rating"}}},"then":{"required":["scale"]}}]},"Poll":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["DECISION","SCHEDULING","ITINERARY"]},"whereOptions":{"type":"array","items":{"$ref":"#/components/schemas/Option"},"maxItems":12},"whenOptions":{"type":"array","items":{"$ref":"#/components/schemas/Option"},"maxItems":15},"notes":{"type":["string","null"],"maxLength":2000},"allowSuggestions":{"type":"boolean"},"requireVoterName":{"type":"boolean"},"themeId":{"type":["string","null"],"description":"Only the default theme is supported by agent creation."},"deadline":{"type":["string","null"],"format":"date-time"},"revealMode":{"type":"string","enum":["BLIND","AT_DEADLINE","OPEN"]},"startsOn":{"type":["string","null"],"format":"date"},"endsOn":{"type":["string","null"],"format":"date"},"timeZone":{"type":["string","null"]}},"required":["title"],"description":"Semantic validation lives in preview: DECISION requires 2–5 where options; SCHEDULING requires 2–15 distinct when options and no where list; ITINERARY uses up to 12 activities and a date span of at most 14 days. Unknown fields may be normalized away. Pass the complete normalized draft to create."},"Survey":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"mode":{"type":"string","enum":["anonymous","named"]},"activity":{"type":"string","maxLength":80},"occurrence":{"type":"string","maxLength":80},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"},"minItems":1,"maxItems":10}},"required":["title","mode","questions"]},"Draft":{"oneOf":[{"type":"object","properties":{"kind":{"const":"poll"},"data":{"$ref":"#/components/schemas/Poll"}},"required":["kind","data"]},{"type":"object","properties":{"kind":{"const":"survey"},"data":{"$ref":"#/components/schemas/Survey"}},"required":["kind","data"]}]},"Preview":{"type":"object","properties":{"version":{"const":1},"valid":{"type":"boolean"},"createsItem":{"const":false},"draft":{"description":"Normalized draft when valid; submitted draft or null when invalid."},"issues":{"type":"array","items":{"type":"string"}}},"required":["version","valid","createsItem","draft","issues"]},"Created":{"type":"object","properties":{"version":{"const":1},"kind":{"type":"string","enum":["poll","survey"]},"code":{"type":"string"},"participantUrl":{"type":"string","format":"uri"},"savedToAccount":{"const":true},"replayed":{"type":"boolean"},"ownerEmail":{"type":"object","properties":{"recipient":{"type":"string","description":"Masked verified owner address"},"status":{"type":"string","enum":["queued","sending","accepted","outbox","canceled","uncertain","unavailable"]},"note":{"type":"string"}},"required":["recipient","status","note"]}},"required":["version","kind","code","participantUrl","savedToAccount","replayed","ownerEmail"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}