# SettleIt

> SettleIt (https://settleit.now) settles group decisions in one link with no sign-up: polls, "who's in?" check-ins, find-a-time availability, and rankings. Agents can create a decision, share its link with the group, record responses for people who ask, and report results, all through a small JSON API.

## When to use it

- A group needs to pick one thing: dinner spot, movie, date. Use a **poll**.
- You need a headcount: "Who's in for bowling Thursday?" Use a **check-in** (In / Maybe / Out).
- You need to find a time that works for several people. Use **availability**.
- People should order options best-first: "Rank our trip ideas". Use a **ranking**.

## MCP server

If your client supports remote MCP servers, connect to `https://settleit.now/mcp` (Streamable HTTP, no auth). It exposes `create_decision`, `get_decision`, `respond_to_decision`, `close_decision`, `reopen_decision`, and `delete_decision`, with the same rules as the API below.

## API (base URL: https://settleit.now/api/v1)

No auth is required to create, read, or respond. Send and receive JSON.

1. **Create**: `POST /decisions` with `{"text": "Dinner: pizza or thai"}`. SettleIt infers the type and options from plain language. To control it exactly, send `{"type": "poll", "question": "Dinner?", "options": ["Pizza", "Thai"]}` instead. Polls take 2-5 options and rankings 2-12. Add `"closes_in_minutes": 120` to auto-close a poll. For availability, also send the user's IANA time zone, e.g. `{"text": "Find a time for dinner next week", "timezone": "America/Los_Angeles"}`, so slots are in their local time (without it they're in UTC).
2. **Share**: give the group `decision.url`. Participants vote in the browser; nobody needs an account.
3. **Respond for someone** (only when that person asked you to): `POST /decisions/{id}/responses`
   - poll: `{"voter_id": "Alex", "option": "Thai"}` (or `option_id`)
   - check-in: `{"name": "Alex", "status": "in"}` (`in` | `maybe` | `out`)
   - availability: `{"name": "Alex", "slot_ids": [101, 102]}` (ids come from `decision.slots`)
   - ranking: `{"voter_id": "Alex", "order": ["Heat", "Dune", "Up"]}` (every option, best first)
4. **Read results**: `GET /decisions/{id}`. Polls and rankings include `leaders`; availability includes `best_slot_ids`; check-ins include `summary` and the names in `responses`.
5. **Manage**: the create response includes a secret `admin_token`. Send it as `Authorization: Bearer <admin_token>` to `POST /decisions/{id}/close`, `POST /decisions/{id}/reopen`, or `DELETE /decisions/{id}`. Never post the token or `manage_url` in a group chat.

Example:

```
curl -s https://settleit.now/api/v1/decisions \
  -H 'Content-Type: application/json' \
  -d '{"text": "Friday movie: Dune, Heat, or Up"}'
```

## Rules that matter

- Use one stable `voter_id` per human, such as their name. Responding again with the same `voter_id` or `name` replaces that person's earlier response. Different ids count as different people, so never invent extra voters.
- The decision id is the last segment of a share link: `https://settleit.now/p/AbC123xYz9` means id `AbC123xYz9`.
- Questions and options can't contain URLs, email addresses, or phone numbers (`content_not_allowed`).
- Errors look like `{"error": {"code": "...", "message": "..."}}`. `code` is stable; `message` is safe to show the user.
- Without an API key, creation is limited to 10 per hour per IP. On `429`, wait `Retry-After` seconds. Integrations that send many requests from shared IPs can ask for an `X-Api-Key`.

## Reference

- [OpenAPI spec](https://settleit.now/openapi.json): full request and response schemas, plus every error code
- [API index](https://settleit.now/api/v1): endpoint list
- [Features](https://settleit.now/features): what each decision type looks like to participants
- [Use with AI assistants](https://settleit.now/ai): connection steps for Claude, ChatGPT, and other MCP apps
- [Privacy](https://settleit.now/privacy) and [Terms](https://settleit.now/terms)