{
  "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": "Intended beta origin; confirm organizer release deployment before use."
    }
  ],
  "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"
                }
              }
            }
          },
          "422": {
            "description": "Unresolved draft; review issues before creating",
            "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"
                }
              }
            }
          },
          "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\u20135 where options; SCHEDULING requires 2\u201315 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"
        ]
      }
    }
  }
}
