TeamSort

TeamSort API documentation for developers and AI agents

One endpoint, no API key: describe a decision, get back a link to a pre-filled poll that the user reviews and publishes. Designed for assistants with a browsing tool, custom GPT actions, MCP servers and plain scripts.

Last updated 2026-08-21

TeamSort API overview

Call GET or POST /api/v1/polls with a natural-language prompt and, optionally, the items to rank. TeamSort drafts a title, instructions and items and returns a URL on teamsort.world/create with everything pre-filled. Hand that URL to the user: they review it, edit if they like, and publish it as a live poll to share with their group. No authentication is required, CORS is open, and responses are never cached (Cache-Control: no-store, private).

TeamSort OpenAPI specification

The machine-readable description of everything below is an OpenAPI 3.1.0 document at teamsort.world/openapi.json. Import it into an API client or an agent framework and you get the endpoints, parameters, response shapes and error codes without reading this page. It is mirrored at /api/openapi.json; /openapi.yaml and /api/openapi.yaml and /swagger.json redirect to it. A RFC 9727 API catalog at /.well-known/api-catalog links the specification and this page for agents that discover services that way.

Authentication

The TeamSort API needs no authentication. There is no API key to request, no OAuth flow, no bearer token and no signup — just call the endpoint. Callers are identified by IP address, and only for rate limiting. If you need a higher limit for a legitimate integration, ask on the contact page and we will raise it for your source. Rate limits are not tied to a paid plan — TeamSort Pro covers the polls themselves, not API volume; see pricing.

Quick start: GET (works from any browsing tool)

curl "https://teamsort.world/api/v1/polls?prompt=Team+offsite+destination&items=Costa+Rica&items=Portugal&items=Japan&items=Iceland"

Repeat the items parameter once per item — it is not comma-separated. Omit items entirely to have them generated from the prompt. HEAD requests return 405: every call mints a draft and costs an AI generation, so link checkers and prefetchers are rejected rather than run silently.

POST (for tool integrations)

curl -X POST https://teamsort.world/api/v1/polls \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Which framework for the rewrite?", "items": ["React", "Vue", "Svelte", "SolidJS"] }'

Parameters

  • prompt (string, required) — what to rank or decide, 1 to 2000 characters. URL-encode it on GET.
  • items (string[], optional) — 2 to 10 items of 1 to 200 characters each. On GET, repeat items= once per item. If the user already listed options, pass them: generation is faster and more faithful.

Response

201 Created
{
  "url": "https://teamsort.world/create?ref=aBcDeFgHiJ",
  "title": "Where should the team offsite be?",
  "items": ["Costa Rica", "Portugal", "Japan", "Iceland"]
}

url is the review link to give the user; it expires 7 days after generation. title is under 80 characters. items is always a flat array of strings, matching your input if you provided one.

Errors

Every error is JSON, never HTML, and always the same shape: error is a sentence for a human, code is a stable machine-readable identifier, hint says what to do about it, and docs links back to this section. Rate-limit responses add retry_after in seconds.

{
  "error": "Draft not found or expired.",
  "code": "draft_not_found",
  "hint": "Draft ids expire 7 days after generation. Create a new one with POST /api/v1/polls.",
  "docs": "https://teamsort.world/developers#errors"
}
  • 400 invalid_request — Check prompt and items against the documented limits, then retry. On GET, repeat the items parameter once per item rather than sending one comma-separated value.
  • 429 rate_limited — Wait the number of seconds in the Retry-After header, then retry. The limit is 20 requests per minute per IP address, plus a global ceiling of 3000 generations per UTC day.
  • 500 generation_failed — Retry once. If it keeps failing the AI generation step is down; report it from the contact page.
  • 404 draft_not_found — Draft ids expire 7 days after generation. Create a new one with POST /api/v1/polls.
  • 404 not_found — Check the path against the OpenAPI specification. The v1 API has two endpoints: /api/v1/polls and /api/v1/drafts/{id}.
  • 405 method_not_allowed — See the Allow response header for the methods this path accepts.

Rate limits

  • 20 requests per minute per IP address.
  • 3000 poll generations per UTC day across all callers — every call runs an AI generation, and this is the spend ceiling.
  • A 429 carries a Retry-After header in seconds and a retry_after field in the body. Back off for that long; do not retry in a tight loop.
  • Retry-After and Link are listed in Access-Control-Expose-Headers, so browser-side callers can read them.

Plans and pricing

The API is free to call and has no paid tier. The polls it drafts follow the same plans as polls made by hand: a free poll stays open for 24 hours and accepts up to 10 voters; TeamSort Pro makes polls permanent with unlimited voters, hidden results, CSV export and drafts. Current plans and prices, in USD, are on the pricing page, which also serves Markdown to clients that send Accept: text/markdown.

Reading a draft back

GET /api/v1/drafts/:id returns the stored draft (title, instructions, items with details) for a ref id, or 404 once it has expired. The create page uses this; most integrations never need it.

TeamSort webhooks

TeamSort does not offer outbound webhooks today, and no endpoint accepts a callback URL. To be told when a poll closes, use the built-in watcher instead: on a poll's results tab, turn on email me results and TeamSort sends the final ranking when the poll closes or expires. If a webhook would unblock an integration, say so on the contact page.

TeamSort MCP server

A TeamSort MCP server is not available yet. Until it ships, the HTTP API on this page is the integration path, and most agent frameworks can import the OpenAPI specification directly as a tool definition.

Notes for agents

  • The returned link is for the user, not for you: present it as a review step — "I've drafted a TeamSort poll, review and publish it here".
  • Do not store the link long-term; it expires in 7 days.
  • Item strings can carry inline context (for example "React — mature ecosystem"); keep each under 200 characters.
  • Be reasonable with volume. The API is rate limited and sustained abuse is blocked.

Reading this site as an agent

Every content page on teamsort.world — the homepage, the guides, and pages like this one — is also available as Markdown: send an Accept: text/markdown header and you get a text/markdown response with the same substance as the HTML. Unknown URLs return a real 404. A short summary of the site lives at llms.txt, the complete API reference at llms-full.txt, the machine-readable API description at openapi.json, and the page index at sitemap.xml.

Questions

Integration questions, rate-limit increases and bug reports: see the contact page.