SettleIt

Create a poll, check-in, availability board, or ranking and get a link to share with the group. Easiest: pass `text` in plain language and SettleIt infers the type and options, e.g. "Dinner: pizza or thai" (poll), "Who's in for bowling Thursday?" (checkin), "Find a time for dinner next week" (availability), "Rank snacks: chips, popcorn, pretzels" (ranking). For exact control, pass `question` plus `options` (2-5 for polls, 2-12 for rankings); with `question` alone you get a check-in. Availability must be created from `text`. For availability, also pass the user's `timezone` (IANA name, e.g. "America/Los_Angeles") so the time slots are in their local time; without it slots are in UTC. Returns the decision (share its `url`), plus an `admin_token` and `manage_url` to keep private.

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 2,
      "maxLength": 1000,
      "description": "Plain-language prompt. Max 200 characters except rankings."
    },
    "type": {
      "type": "string",
      "enum": [
        "poll",
        "checkin",
        "availability",
        "ranking"
      ],
      "description": "Force a type. Optional with text."
    },
    "question": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200
    },
    "options": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80
      },
      "maxItems": 12,
      "description": "Unique choices, used with question."
    },
    "closes_in_minutes": {
      "type": "integer",
      "minimum": 10,
      "maximum": 10080,
      "description": "Polls only: auto-close after this many minutes."
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "description": "Availability: the user's IANA time zone, e.g. \"America/Los_Angeles\". Slots and words like \"tomorrow\" use it. Defaults to UTC."
    }
  },
  "additionalProperties": false
}

Read a decision and its current results: votes and leaders for polls, rankings with points, In/Maybe/Out names for check-ins, and per-slot counts plus best_slot_ids for availability. Also returns the option or slot ids that respond_to_decision needs.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "string",
      "description": "Decision id or SettleIt link, e.g. \"AbC123xYz9\" or \"https://settleit.now/p/AbC123xYz9\"."
    }
  },
  "required": [
    "decision_id"
  ],
  "additionalProperties": false
}

Record one person's answer, only when that person asked you to. Which fields you need depends on the decision's type (get_decision shows it in `respond.fields`): - poll: voter_id + option (exact label) or option_id - ranking: voter_id + order (every option label or id, best first) - checkin: name + status (in, maybe, out) - availability: name + slot_ids (from get_decision `slots`) Answering again with the same voter_id or name (case-insensitive) replaces that person's earlier answer.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "string",
      "description": "Decision id or SettleIt link, e.g. \"AbC123xYz9\" or \"https://settleit.now/p/AbC123xYz9\"."
    },
    "voter_id": {
      "type": "string",
      "maxLength": 128,
      "description": "poll, ranking: stable id for the person, e.g. their name."
    },
    "option": {
      "type": "string",
      "description": "poll: exact option label."
    },
    "option_id": {
      "type": "integer",
      "description": "poll: option id (alternative to option)."
    },
    "order": {
      "type": "array",
      "items": {
        "type": [
          "string",
          "integer"
        ]
      },
      "description": "ranking: every option label or id, best first."
    },
    "name": {
      "type": "string",
      "maxLength": 80,
      "description": "checkin, availability: the person's name."
    },
    "status": {
      "type": "string",
      "enum": [
        "in",
        "maybe",
        "out"
      ],
      "description": "checkin"
    },
    "slot_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "availability: every slot the person can make."
    }
  },
  "required": [
    "decision_id"
  ],
  "additionalProperties": false
}

Stop accepting responses. Results stay visible. Requires the admin_token.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "string",
      "description": "Decision id or SettleIt link, e.g. \"AbC123xYz9\" or \"https://settleit.now/p/AbC123xYz9\"."
    },
    "admin_token": {
      "type": "string",
      "description": "The admin_token returned by create_decision."
    }
  },
  "required": [
    "decision_id",
    "admin_token"
  ],
  "additionalProperties": false
}

Accept responses again after closing (clears an automatic close time that has passed). Requires the admin_token.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "string",
      "description": "Decision id or SettleIt link, e.g. \"AbC123xYz9\" or \"https://settleit.now/p/AbC123xYz9\"."
    },
    "admin_token": {
      "type": "string",
      "description": "The admin_token returned by create_decision."
    }
  },
  "required": [
    "decision_id",
    "admin_token"
  ],
  "additionalProperties": false
}

Permanently delete a decision and all its responses. The share link stops working. This cannot be undone, so confirm with the user first. Requires the admin_token.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "string",
      "description": "Decision id or SettleIt link, e.g. \"AbC123xYz9\" or \"https://settleit.now/p/AbC123xYz9\"."
    },
    "admin_token": {
      "type": "string",
      "description": "The admin_token returned by create_decision."
    }
  },
  "required": [
    "decision_id",
    "admin_token"
  ],
  "additionalProperties": false
}