# Welcome to Geekbot's API

Version: 1.0.0

Base URL: https://api.geekbot.com

Authentication: send your API key in the `Authorization` header.

**API reference**

Use the Geekbot API to manage standups, polls, reports, users, and team data from your own tools and workflows.

All requests are made over HTTPS to `https://api.geekbot.com` and authenticated with an API key sent in the Authorization header.

The API returns JSON responses and supports common workflows such as retrieving the current user, listing teams and standups, creating polls, submitting reports, and starting standups programmatically.

**Current and Legacy endpoints**

The Geekbot API has two sets of endpoints, grouped as **Current** and **Legacy** in the sidebar.

The **Current** endpoints (served under `/v2/`) are the recommended choice for new integrations. They use a consistent response envelope (`data`, `next_cursor`, `has_more`), cursor-based pagination, opt-in field expansion via `?include=`, structured errors (`{ error: { code, message } }`), and an `Idempotency-Key` header for safe retries on write endpoints. The official [geekbot-cli](https://github.com/geekbot-com/geekbot-cli) targets these endpoints.

The **Legacy** endpoints (served under `/v1/`) are retained for backwards compatibility. They currently overlap with parts of the current API — both are fully supported, and you can mix them per request. More resources will be added to the current set over time.

**Geekbot CLI & AI Skill**

Submit reports, analyse past responses, and manage standups and polls from your terminal or AI coding agent. Works as a standalone CLI and as a skill for Claude Code, Cursor, Windsurf, and Copilot.

[View on GitHub](https://github.com/geekbot-com/geekbot-cli)

**Geekbot MCP Server**

Connect your AI assistant to Geekbot via the Model Context Protocol. Query standups, fetch reports, and post updates using natural language in Claude Desktop, Cursor, or Windsurf.

[View on GitHub](https://github.com/geekbot-com/geekbot-mcp)

---

## Current

### User

Retrieve information about the authenticated user, their teams, and their standups.

#### GET /v1/me — Get current user

Returns the authenticated user and basic information about the team associated with the provided API key.

**Responses**

- `200` — Success
  - `user`: object — Current user information.
    - `id`: string — User unique ID.
    - `username`: string — Username.
    - `realname`: string — User's real name.
    - `firstname`: string — User's first name.
    - `email`: string — User's email address.
    - `profile_img`: string — Profile image URL (192px).
    - `timezone`: string — User's timezone.
    - `is_admin`: boolean — Whether user is an admin.
    - `is_billing_admin`: boolean — Whether user is a billing admin.
    - `role`: string — User's role description.
  - `team`: object — Team information.
    - `id`: number — Team ID.
    - `name`: string — Team name.

#### GET /v1/me/teams — List user teams

Returns the teams the authenticated user belongs to. This endpoint currently returns only the team associated with the provided API key.

**Responses**

- `200` — Success
  - `teams`: array<object> — List of teams the user belongs to.
    - `id`: number — Team ID.
    - `name`: string — Team name.
    - `is_admin`: boolean — Whether user is admin in this team.
    - `standup_count`: number — Number of standups in the team.

#### GET /v1/me/standups — List user standups

Returns the standups the authenticated user participates in. This endpoint is an alias of `/v1/standups` and returns the same detailed response format.

**Responses**

- `200` — Success
  - array of objects:
    - `id`: number — Standup unique id.
    - `name`: string — Standup name.
    - `time`: string — Time standup starts.
    - `wait_time`: number — Minutes to wait after user logs in before asking a question. Null value means no automated asking.
    - `timezone`: string — Timezone used to calculate standup time.
    - `days`: array<string> — List of days when standup is active.
    - `channel`: string — Channel where the standup updates are posted.
    - `questions`: array<object> — List of standup questions.
    - `users`: array<object> — List of users taking part in the standup.
    - `sync_channel_members`: boolean — Standup participants will be synced with channel members.

### Team

Retrieve team information associated with the authenticated API key.

#### GET /v1/teams/ — List teams

Returns the team associated with the authenticated API key.

**Responses**

- `200` — Success
  - `id`: number — Team unique id.
  - `name`: string — Team name.
  - `users`: array<object> — Users participating in at least one standup visible to the authenticated user.
    - `id`: string — User unique id.
    - `role`: string — User role.
    - `email`: string — User email.
    - `username`: string — User username.
    - `realname`: string — User real name.
    - `profile_img`: string — User profile image URL.

### Poll

v2 poll endpoints. Standard envelope, cursor pagination, opt-in includes.
The votes endpoint returns aggregated results (counts per choice, category
rollups for open-ended) scoped by default to the latest poll instance.

#### GET /v2/polls — List polls

Returns active and paused polls created by the caller. Polls are only visible to their creator.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `state` | query | no | string | Comma-separated subset of: active, paused. Default: both. |
| `is_anonymous` | query | no | string (enum: true, false) | Filter by anonymity. |
| `broadcast_channel` | query | no | string | Restrict to a specific channel id (e.g. "C12345"). |
| `created_since` | query | no | string | ISO 8601 or YYYY-MM-DD (inclusive). |
| `created_until` | query | no | string | ISO 8601 or YYYY-MM-DD (exclusive). |
| `cursor` | query | no | string | Opaque pagination cursor from a previous response. Must be replayed with the same filters that produced it; reusing it with different filters returns 400. |
| `limit` | query | no | number (range: 1..100; default: 25) | Page size. |
| `include` | query | no | string (enum: questions, member_username, member_realname, member_email) | Comma-separated extra fields to expand. The `member_*` values enrich each entry in `data.members` with the corresponding user field. |

**Responses**

- `200` — Success
  - `data`: array<object> — List of polls.
    - `id`: number — Poll id.
    - `name`: string — Poll name.
    - `state`: string (enum: active, paused) — Poll state.
    - `time`: string — Time of day the poll triggers.
    - `timezone`: string — Poll timezone.
    - `days`: array<string> — Days the poll is active.
    - `broadcast_channel`: object — Channel where the poll is posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the poll is anonymous.
    - `owner`: string — User id of the poll creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members invited to the poll.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
    - `questions`: array<object> — Only present when include=questions.
      - `id`: number — Question id.
      - `text`: string — Question text shown to voters.
      - `position`: number — Display order within the poll (0-indexed).
      - `answer_type`: string — Answer type (e.g. multiple_choice, open_ended).
      - `choices`: array<string> — Answer choices (populated for multiple-choice questions; empty array otherwise).
  - `next_cursor`: string — Cursor for the next page; null when has_more is false.
  - `has_more`: boolean — Whether more pages exist.
- `400` — `INVALID_PARAMETER` — Validation failed (bad date, bad cursor, unknown include, etc.).

#### POST /v2/polls — Create poll

Creates a one-shot poll that posts to `broadcast_channel` on publish. Members are auto-synced from the broadcast channel.

**Request body** (`application/json`)

- `name`: string (required) — Poll name.
- `question`: string (required) — Poll question text.
- `choices`: array<string> (required) — Answer choices (at least 2).
- `broadcast_channel`: string (required) — Channel id or name where the poll is posted.
- `duration`: number — Duration the poll stays open, in minutes.

**Responses**

- `201` — Success
  - `data`: object
    - `id`: number — Poll id.
    - `name`: string — Poll name.
    - `state`: string (enum: active, paused) — Poll state.
    - `time`: string — Time of day the poll triggers.
    - `timezone`: string — Poll timezone.
    - `days`: array<string> — Days the poll is active.
    - `broadcast_channel`: object — Channel where the poll is posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the poll is anonymous.
    - `owner`: string — User id of the poll creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members invited to the poll.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
- `400` — `INVALID_PARAMETER` — Validation failed (missing/invalid body field, or malformed Idempotency-Key). `CHANNEL_NOT_FOUND` — `broadcast_channel` could not be resolved.
- `422` — `MISMATCHED_IDEMPOTENCY_BODY` — Idempotency-Key reused with a different request body.

#### GET /v2/polls/{pollId} — Get poll

Returns one poll the caller created (active or paused). Returns 404 for any non-visible poll — including polls owned by other users or in archived/draft state — to avoid leaking existence.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pollId` | path | yes | number | Poll id. |
| `include` | query | no | string (enum: questions, member_username, member_realname, member_email) | Comma-separated extra fields to expand. The `member_*` values enrich each entry in `data.members` with the corresponding user field. |

**Responses**

- `200` — Success
  - `data`: object
    - `id`: number — Poll id.
    - `name`: string — Poll name.
    - `state`: string (enum: active, paused) — Poll state.
    - `time`: string — Time of day the poll triggers.
    - `timezone`: string — Poll timezone.
    - `days`: array<string> — Days the poll is active.
    - `broadcast_channel`: object — Channel where the poll is posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the poll is anonymous.
    - `owner`: string — User id of the poll creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members invited to the poll.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
    - `questions`: array<object> — Only present when include=questions.
      - `id`: number — Question id.
      - `text`: string — Question text shown to voters.
      - `position`: number — Display order within the poll (0-indexed).
      - `answer_type`: string — Answer type (e.g. multiple_choice, open_ended).
      - `choices`: array<string> — Answer choices (populated for multiple-choice questions; empty array otherwise).
- `404` — `NOT_FOUND` — The poll does not exist or is not visible to the caller.

#### GET /v2/polls/{pollId}/votes — Get poll votes

Returns aggregated vote results for the poll. Without time filters, returns only the latest broadcast instance. With since/until, returns every instance whose broadcast date falls in the range.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pollId` | path | yes | number | Poll id. |
| `since` | query | no | string | ISO 8601 or YYYY-MM-DD (inclusive). |
| `until` | query | no | string | ISO 8601 or YYYY-MM-DD (exclusive). Defaults to now. |

**Responses**

- `200` — Success
  - `data`: object — Poll-results object.
    - `poll_id`: number — Poll id.
    - `poll_name`: string — Poll name.
    - `is_anonymous`: boolean — Whether the poll is anonymous.
    - `instances`: array<object> — Instances in scope (latest only by default).
      - `instance_id`: number — Poll instance id.
      - `date`: string — Broadcast date (YYYY-MM-DD).
      - `questions`: array<object> — Aggregated per-question results.
        - `question_id`: number — Question id.
        - `text`: string — Question text.
        - `answer_type`: string (enum: multiple_choice, open_ended) — Answer type.
        - `total_responses`: number — Total answers submitted.
        - `total_responders`: number — Distinct responders.
        - `choices`: array<object> — Multi-choice only: per-choice vote counts.
          - `text`: string — Choice label.
          - `votes`: number — Vote count for this choice.
          - `voters`: array<string> — Voter user ids. Null when is_anonymous.
        - `categorization_status`: string — Open-ended only: pending|processing|completed|failed|null.
        - `categories`: array<object> — Open-ended only: counts per assigned category (when status=completed).
          - `name`: string — Category name.
          - `count`: number — Number of answers in this category (may sum to more than total_responses for multi-label).
        - `responses`: array<object> — Open-ended only: raw responses with category labels.
          - `text`: string — Response text.
          - `categories`: array<string> — Categories assigned to this response (when status=completed).
          - `user_id`: string — Responder user id. Null when is_anonymous.
- `400` — `INVALID_PARAMETER` — Validation failed (bad date, reversed range, etc.).
- `404` — `NOT_FOUND` — The poll does not exist or is not visible to the caller.

### Report

v2 report endpoints. Standard envelope, cursor pagination, summary/full views.
Write methods (POST/PATCH/DELETE) accept an `Idempotency-Key` header for safe
retries. Time-window queries are capped at 90 days.

#### GET /v2/reports — List reports

Returns submitted reports from active standups the caller can see. Time window defaults to the last 7 days when neither `since` nor `until` is provided. The window cannot exceed 90 days — wider ranges return 400.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `since` | query | no | string | ISO 8601 or YYYY-MM-DD (inclusive). Default: now - 7 days. |
| `until` | query | no | string | ISO 8601 or YYYY-MM-DD (exclusive). Default: now. |
| `standup_id` | query | no | number | Restrict to a single standup. |
| `user_id` | query | no | string | Restrict to a single user (Slack-style id, e.g. "U123"). When filtering by another user's id, reports from anonymous standups are excluded. |
| `cursor` | query | no | string | Opaque pagination cursor from a previous response. Must be replayed with the same since/until/standup_id/user_id that produced it; reusing it with different filters returns 400. |
| `limit` | query | no | number (range: 1..100; default: 25) | Page size. |
| `view` | query | no | string (enum: summary, full; default: full) | Response shape. Summary omits the answers block. |

**Responses**

- `200` — Success
  - `data`: array<object> — List of reports.
    - `id`: number — Report id.
    - `standup_id`: number — Standup id the report belongs to.
    - `standup_name`: string — Standup name.
    - `user_id`: string — User id of the report author. Null when the report is anonymous (standup or report-level flag).
    - `posted_at`: string — ISO 8601 timestamp when the report was submitted.
    - `is_anonymous`: boolean — Whether this report is anonymous (true if either the standup or the report itself was anonymous at submission).
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `answers`: array<object> — Per-question answers.
      - `id`: number — Answer id.
      - `question_id`: number — Question id the answer belongs to.
      - `question`: string — Question text shown to the user.
      - `answer`: string — Plain-text answer.
  - `next_cursor`: string — Cursor for the next page; null when has_more is false.
  - `has_more`: boolean — Whether more pages exist.
- `400` — `INVALID_PARAMETER` — Validation failed (invalid date, range over 90 days, reversed range, bad cursor, etc.).

#### POST /v2/reports — Create report

Submits a report for one of the caller's active standups. All standup questions must be answered in a single call. Broadcasts the report to the standup's channel on success.

**Request body** (`application/json`)

- `standup_id`: number (required) — Standup id.
- `answers`: array<object> (required) — One entry per standup question.
- `answers.question_id`: number (required) — Question id (must belong to the standup).
- `answers.text`: string (required) — Plain-text answer.

**Responses**

- `200` — Success
  - `data`: object
    - `id`: number — Report id.
    - `standup_id`: number — Standup id the report belongs to.
    - `standup_name`: string — Standup name.
    - `user_id`: string — User id of the report author. Null when the report is anonymous (standup or report-level flag).
    - `posted_at`: string — ISO 8601 timestamp when the report was submitted.
    - `is_anonymous`: boolean — Whether this report is anonymous (true if either the standup or the report itself was anonymous at submission).
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `answers`: array<object> — Per-question answers.
      - `id`: number — Answer id.
      - `question_id`: number — Question id the answer belongs to.
      - `question`: string — Question text shown to the user.
      - `answer`: string — Plain-text answer.
- `400` — `INVALID_PARAMETER` — Missing/invalid field, wrong answer count, unknown question_id, or malformed Idempotency-Key.
- `404` — `NOT_FOUND` — The standup does not exist, is paused, is a poll, or the caller is not a member.
- `422` — `MISMATCHED_IDEMPOTENCY_BODY` — Idempotency-Key reused with a different request body.

#### GET /v2/reports/{reportId} — Get report

Returns one submitted report from a standup the caller can see. Returns 404 for any non-visible report — including pending reports, reports from paused or confidential standups not owned by the caller, or other teams — to avoid leaking existence.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `reportId` | path | yes | number | Report id. |

**Responses**

- `200` — Success
  - `data`: object
    - `id`: number — Report id.
    - `standup_id`: number — Standup id the report belongs to.
    - `standup_name`: string — Standup name.
    - `user_id`: string — User id of the report author. Null when the report is anonymous (standup or report-level flag).
    - `posted_at`: string — ISO 8601 timestamp when the report was submitted.
    - `is_anonymous`: boolean — Whether this report is anonymous (true if either the standup or the report itself was anonymous at submission).
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `answers`: array<object> — Per-question answers.
      - `id`: number — Answer id.
      - `question_id`: number — Question id the answer belongs to.
      - `question`: string — Question text shown to the user.
      - `answer`: string — Plain-text answer.
- `404` — `NOT_FOUND` — The report does not exist or is not visible to the caller.

#### PATCH /v2/reports/{reportId} — Update report

Updates one or more answers on a report the caller owns. Partial updates are allowed — only the supplied answers are changed. If the report was broadcasted, the broadcast message is updated.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `reportId` | path | yes | number | Report id. |

**Request body** (`application/json`)

- `answers`: array<object> (required) — One or more answers to update.
- `answers.question_id`: number (required) — Question id (must belong to the report's standup).
- `answers.text`: string (required) — New plain-text answer.

**Responses**

- `200` — Success
  - `data`: object
    - `id`: number — Report id.
    - `standup_id`: number — Standup id the report belongs to.
    - `standup_name`: string — Standup name.
    - `user_id`: string — User id of the report author. Null when the report is anonymous (standup or report-level flag).
    - `posted_at`: string — ISO 8601 timestamp when the report was submitted.
    - `is_anonymous`: boolean — Whether this report is anonymous (true if either the standup or the report itself was anonymous at submission).
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `answers`: array<object> — Per-question answers.
      - `id`: number — Answer id.
      - `question_id`: number — Question id the answer belongs to.
      - `question`: string — Question text shown to the user.
      - `answer`: string — Plain-text answer.
- `400` — `INVALID_PARAMETER` — Missing/invalid field or unknown question_id.
- `404` — `NOT_FOUND` — The report does not exist or the caller is not the author.

#### DELETE /v2/reports/{reportId} — Delete report

Discards a report the caller owns. Removes the broadcast message if one was posted. Listings exclude the report, but its history is retained.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `reportId` | path | yes | number | Report id. |

**Responses**

- `200` — Success
  - `success`: boolean — Always true on success.
- `404` — `NOT_FOUND` — The report does not exist or the caller is not the author.

### Standup

v2 standup endpoints. Standard envelope, cursor pagination, opt-in includes.
See `GET /v2/standups` for the canonical shape.

#### GET /v2/standups — List standups

Returns active and paused standups visible to the caller. A standup is visible when the caller is a member of it (for non-confidential standups) or its creator (for confidential standups). Polls are excluded.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `state` | query | no | string | Comma-separated subset of: active, paused. Default: both. |
| `is_anonymous` | query | no | string (enum: true, false) | Filter by anonymity. |
| `broadcast_channel` | query | no | string | Restrict to a specific channel id (e.g. "C12345"). |
| `created_since` | query | no | string | ISO 8601 or YYYY-MM-DD (inclusive). |
| `created_until` | query | no | string | ISO 8601 or YYYY-MM-DD (exclusive). |
| `cursor` | query | no | string | Opaque pagination cursor from a previous response. Must be replayed with the same filters that produced it; reusing it with different filters returns 400. |
| `limit` | query | no | number (range: 1..100; default: 25) | Page size. |
| `include` | query | no | string (enum: questions, member_username, member_realname, member_email) | Comma-separated extra fields to expand. The `member_*` values enrich each entry in `data.members` with the corresponding user field. |

**Responses**

- `200` — Success
  - `data`: array<object> — List of standups.
    - `id`: number — Standup id.
    - `name`: string — Standup name.
    - `state`: string (enum: active, paused) — Standup state.
    - `time`: string — Time of day the standup runs.
    - `wait_time`: number — Minutes to wait after login before asking. May be null.
    - `timezone`: string — Standup timezone.
    - `days`: array<string> — Days the standup is active.
    - `broadcast_channel`: object — Channel where updates are posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the standup is anonymous.
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `owner`: string — User id of the standup creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members participating in the standup.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
    - `questions`: array<object> — Only present when include=questions.
      - `id`: number — Question id.
      - `text`: string — Question text shown to members.
      - `position`: number — Display order within the standup (0-indexed).
      - `answer_type`: string — Answer type (e.g. text, multiple_choice).
      - `choices`: array<string> — Answer choices (populated for multiple-choice questions; empty array otherwise).
  - `next_cursor`: string — Cursor for the next page; null when has_more is false.
  - `has_more`: boolean — Whether more pages exist.
- `400` — `INVALID_PARAMETER` — Validation failed (bad date, bad cursor, unknown include, etc.).

#### POST /v2/standups — Create standup

Creates a non-confidential standup. Members are taken from `users` if provided; otherwise synced from `sync_channel` (falling back to `broadcast_channel`).

**Request body** (`application/json`)

- `name`: string — Standup name. Defaults to "Standup #<broadcast channel>".
- `questions`: array<object> (required) — List of questions. Each item: { "text": String, "choices"?: String[] }. When `choices` is present the question is multiple-choice.
- `days`: array<string> (required) — Workdays (e.g. ["Mon","Tue","Wed","Thu","Fri"]).
- `time`: string (required) — Time of day, "HH:MM" (or "HH:MM:SS").
- `broadcast_channel`: string (required) — Channel id or name where reports are posted.
- `sync_channel`: string — Channel id or name to sync members from.
- `users`: array<string> — Explicit list of user ids; mutually exclusive with `sync_channel` semantics.
- `timezone`: string — Timezone used to compute the ask time.
- `is_anonymous`: boolean — Whether responses are anonymous.

**Responses**

- `201` — Success
  - `data`: object
    - `id`: number — Standup id.
    - `name`: string — Standup name.
    - `state`: string (enum: active, paused) — Standup state.
    - `time`: string — Time of day the standup runs.
    - `wait_time`: number — Minutes to wait after login before asking. May be null.
    - `timezone`: string — Standup timezone.
    - `days`: array<string> — Days the standup is active.
    - `broadcast_channel`: object — Channel where updates are posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the standup is anonymous.
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `owner`: string — User id of the standup creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members participating in the standup.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
- `400` — `INVALID_PARAMETER` — Validation failed (missing/invalid body field, or malformed Idempotency-Key). `CHANNEL_NOT_FOUND` — `broadcast_channel` or `sync_channel` could not be resolved. `USER_NOT_FOUND` — One or more ids in `users` are not known to the team.
- `422` — `MISMATCHED_IDEMPOTENCY_BODY` — Idempotency-Key reused with a different request body.

#### GET /v2/standups/{standupId} — Get standup

Returns one standup the caller can see (active or paused). Returns 404 for any non-visible standup — including draft/archived states, polls, other team, or confidential standups not owned by the caller — to avoid leaking existence.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `standupId` | path | yes | number | Standup id. |
| `include` | query | no | string (enum: questions, member_username, member_realname, member_email) | Comma-separated extra fields to expand. The `member_*` values enrich each entry in `data.members` with the corresponding user field. |

**Responses**

- `200` — Success
  - `data`: object
    - `id`: number — Standup id.
    - `name`: string — Standup name.
    - `state`: string (enum: active, paused) — Standup state.
    - `time`: string — Time of day the standup runs.
    - `wait_time`: number — Minutes to wait after login before asking. May be null.
    - `timezone`: string — Standup timezone.
    - `days`: array<string> — Days the standup is active.
    - `broadcast_channel`: object — Channel where updates are posted. May be null.
      - `id`: string — Channel id.
      - `name`: string — Channel name.
    - `is_anonymous`: boolean — Whether the standup is anonymous.
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `owner`: string — User id of the standup creator.
    - `created`: string — ISO 8601 timestamp.
    - `updated`: string — ISO 8601 timestamp.
    - `members`: array<object> — Members participating in the standup.
      - `id`: string — Member user id.
      - `email`: string — Member email address. Returned only when `member_email` is in `include`.
      - `username`: string — Member username. Returned only when `member_username` is in `include`.
      - `realname`: string — Member display name. Returned only when `member_realname` is in `include`.
    - `questions`: array<object> — Only present when include=questions.
      - `id`: number — Question id.
      - `text`: string — Question text shown to members.
      - `position`: number — Display order within the standup (0-indexed).
      - `answer_type`: string — Answer type (e.g. text, multiple_choice).
      - `choices`: array<string> — Answer choices (populated for multiple-choice questions; empty array otherwise).
- `404` — `NOT_FOUND` — The standup does not exist or is not visible to the caller.

## Legacy

### Poll (legacy)

Older v1 poll endpoints retained for backwards compatibility. New integrations should use the current Poll endpoints.

#### GET /v1/polls — List polls

Returns the polls the authenticated user participates in.

**Responses**

- `200` — Success
  - array of objects:
    - `id`: number — Poll unique id.
    - `name`: string — Poll name.
    - `time`: string — Poll time.
    - `timezone`: string — Poll timezone.
    - `questions`: array<object> — Poll questions.
      - `id`: number — Question unique id.
      - `text`: string — Question text.
      - `answer_type`: string — Question answer type.
      - `answer_choices`: array<string> — Question answer choices.
      - `add_own_options`: boolean — Whether to allow users to add their own options.
      - `one_option_limit`: boolean — Whether to limit the number of options to one.
    - `users`: array<object> — Poll users.
      - `id`: number — User unique id.
      - `role`: string — User role.
      - `email`: string — User email.
      - `username`: string — User username.
      - `realname`: string — User real name.
      - `profile_img`: string — User profile image.
    - `recurrence`: object — Poll recurrence.
    - `sync_channel_members`: boolean — Whether to sync channel members.
    - `sync_channel`: string — Sync channel.
    - `anonymous`: boolean — Whether to use anonymous mode.
    - `intro`: string — Poll intro.
    - `creator`: object — Poll creator.
    - `users_total`: number — Total number of users.
    - `paused`: boolean — Whether the poll is paused.

#### POST /v1/polls — Create poll

Creates a one-time poll in the specified channel and invites current channel members. The authenticated user becomes the poll creator.

**Request body** (`application/json`)

- `name`: string (required) — Poll name.
- `channel`: string (required) — Channel where the poll is posted and the members are invited.
- `question`: string (required) — Poll question.
- `choices`: array<string> (required) — Poll choices.
- `duration`: number (required) — Duration of the poll in minutes.

**Responses**

- `200` — Success
  - `id`: number — Poll unique id.
  - `name`: string — Poll name.
  - `time`: string — Poll time.
  - `timezone`: string — Poll timezone.
  - `questions`: array<object> — Poll questions.
    - `id`: number — Question unique id.
    - `text`: string — Question text.
    - `answer_type`: string — Question answer type.
    - `answer_choices`: array<string> — Question answer choices.
    - `add_own_options`: boolean — Whether to allow users to add their own options.
    - `one_option_limit`: boolean — Whether to limit the number of options to one.
  - `users`: array<object> — Poll users.
    - `id`: number — User unique id.
    - `role`: string — User role.
    - `email`: string — User email.
    - `username`: string — User username.
    - `realname`: string — User real name.
    - `profile_img`: string — User profile image.
  - `recurrence`: object — Poll recurrence.
  - `sync_channel_members`: boolean — Whether to sync channel members.
  - `sync_channel`: string — Sync channel.
  - `anonymous`: boolean — Whether to use anonymous mode.
  - `intro`: string — Poll intro.
  - `creator`: object — Poll creator.
  - `users_total`: number — Total number of users.
  - `paused`: boolean — Whether the poll is paused.

#### GET /v1/polls/{id} — Get poll

Returns a poll by ID. The poll must belong to the authenticated team, and the authenticated user must have access to it.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Poll unique id. |

**Responses**

- `200` — Success
  - `id`: number — Poll unique id.
  - `name`: string — Poll name.
  - `time`: string — Poll time.
  - `timezone`: string — Poll timezone.
  - `questions`: array<object> — Poll questions.
    - `id`: number — Question unique id.
    - `text`: string — Question text.
    - `answer_type`: string — Question answer type.
    - `answer_choices`: array<string> — Question answer choices.
    - `add_own_options`: boolean — Whether to allow users to add their own options.
    - `one_option_limit`: boolean — Whether to limit the number of options to one.
  - `users`: array<object> — Poll users.
    - `id`: number — User unique id.
    - `role`: string — User role.
    - `email`: string — User email.
    - `username`: string — User username.
    - `realname`: string — User real name.
    - `profile_img`: string — User profile image.
  - `recurrence`: object — Poll recurrence.
  - `sync_channel_members`: boolean — Whether to sync channel members.
  - `sync_channel`: string — Sync channel.
  - `anonymous`: boolean — Whether to use anonymous mode.
  - `intro`: string — Poll intro.
  - `creator`: object — Poll creator.
  - `users_total`: number — Total number of users.
  - `paused`: boolean — Whether the poll is paused.

#### GET /v1/polls/{id}/votes — Get poll results

Returns aggregated voting results for a poll. You can optionally filter results by date range using the `from` and `to` query parameters.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Poll unique id. |
| `from` | query | no | string | Votes from date. |
| `to` | query | no | string | Votes to date. |

**Responses**

- `200` — Success
  - `total_results`: number — Total number of poll instances in the result.
  - `questions`: array<object> — Poll questions with aggregated votes.
    - `id`: number — Question unique id.
    - `text`: string — Question text.
    - `answer_type`: string — Question answer type.
    - `results`: array<object> — Per-instance vote breakdown for this question.
      - `date`: string — Result date.
      - `answers`: array<object> — Result answers.
        - `text`: string — Answer text.
        - `votes`: number — Answer votes.
        - `percentage`: number — Answer percentage.
        - `users`: array<object> — Users who chose this answer (when poll is not anonymous).
          - `id`: string — User unique id.
          - `role`: string — User role.
          - `email`: string — User email.
          - `username`: string — User username.
          - `realname`: string — User real name.
          - `profile_img`: string — User profile image.
  - `instances`: array<object> — Poll instances included in the result.
    - `id`: number — Instance unique id.
    - `date`: string — Instance date.
    - `answer_count`: number — Number of answers in this instance.

### Report (legacy)

Older v1 report endpoints retained for backwards compatibility. New integrations should use the current Report endpoints.

#### GET /v1/reports/ — List reports

Returns standup reports visible to the authenticated user. You can filter results by standup, user, date range, and question ID.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `limit` | query | no | number | Limit number of reports. Default is 30, maximum limit is 100. |
| `standup_id` | query | no | number | Receive reports for the specified standup only. |
| `user_id` | query | no | number | Receive reports from the specified user only. |
| `after` | query | no | number | Receive reports given after the specified timestamp. |
| `before` | query | no | number | Receive reports given before the specified timestamp. |
| `question_ids` | query | no | array<number> | Receive answers to specific questions only. |
| `html` | query | no | boolean | Receive anwers with html formatting. |

**Responses**

- `200` — Success
  - array of objects:
    - `id`: number — Report unique id.
    - `standup_id`: number — Standup unique id.
    - `timestamp`: number — Report timestamp (Unix).
    - `channel`: string — Channel where the standup is posted.
    - `is_anonymous`: boolean — Whether the standup is anonymous.
    - `broadcast_thread`: boolean — Whether updates are posted in a thread.
    - `is_confidential`: boolean — Whether the standup is confidential.
    - `member`: object — User who submitted the report (omitted when anonymous).
      - `id`: string — User unique id.
      - `username`: string — User username.
      - `realname`: string — User real name.
      - `profileImg`: object — User profile image URLs by size.
    - `questions`: array<object> — Report answers.
      - `id`: number — Answer unique id.
      - `question`: string — Question text.
      - `question_id`: number — Question unique id.
      - `color`: string — Question color.
      - `answer`: string — Answer text (HTML when html=true).
      - `images`: array<object> — Images attached to the answer.
        - `title`: string — Image title.
        - `image_url`: string — Image URL.

#### POST /v1/reports/ — Create report

Creates a new standup report on behalf of the authenticated user. The standup must exist, be active, and include the authenticated user as a participant or creator.

**Request body** (`application/json`)

- `standup_id`: integer (required) — Standup unique id
- `answers`: array<string> (required) — Associative array with question ids that point to text answers

**Responses**

- `200` — Success
  - `id`: number — Report unique id.
  - `slack_ts`: string — Slack message timestamp.
  - `standup_id`: number — Standup unique id.
  - `timestamp`: number — Report timestamp (Unix).
  - `started_at`: number — When the report was started (Unix).
  - `done_at`: number — When the report was completed (Unix).
  - `broadcasted_at`: string — When the report was broadcast to the channel.
  - `channel`: string — Channel where the standup is posted.
  - `member`: object — User who submitted the report.
    - `id`: string — User unique id.
    - `role`: string — User role.
    - `username`: string — User username.
    - `realname`: string — User real name.
    - `profileImg`: object — User profile image URLs by size.
  - `answers`: array<object> — Submitted answers.
    - `id`: number — Answer unique id.
    - `answer`: string — Answer text.
    - `question`: string — Question text.
    - `question_id`: number — Question unique id.
    - `color`: string — Question color.
    - `images`: array<object> — Images attached to the answer.

### Standup (legacy)

Older v1 standup endpoints retained for backwards compatibility. New integrations should use the current Standup endpoints.

#### GET /v1/standups/ — List standups

Returns the standups available to the authenticated user. Draft or restricted standups are hidden unless the authenticated user is the creator. Admins can request the full list by using the `admin` query parameter.

**Responses**

- `200` — Success
  - array of objects:
    - `id`: number — Standup unique id.
    - `name`: string — Standup name.
    - `time`: string — Time standup starts.
    - `wait_time`: number — Minutes to wait after user logs in before asking a question. Null value means no automated asking.
    - `timezone`: string — Timezone used to calculate standup time.
    - `days`: array<string> — List of days when standup is active.
    - `channel`: string — Channel where the standup updates are posted.
    - `questions`: array<object> — List of standup questions.
    - `users`: array<object> — List of users taking part in the standup.
    - `sync_channel_members`: boolean — Standup participants will be synced with channel members.

#### POST /v1/standups/ — Create standup

Creates a new standup in the authenticated team. Participants can be provided explicitly with `users`, or derived from a channel when `sync_channel_members` is enabled.

**Request body** (`application/json`)

- `name`: string (required) — Standup name.
- `channel`: string (required) — Channel where the standup updates are posted.
- `time`: string (required) — Time to ask standup in "HH:MM:SS" format.
- `timezone`: string (required) — Timezone to use when calculating time to ask. If not specified, default is user local.
- `wait_time`: number — Minutes to wait after team member is online before asking a question. Set to null so that users do not get asked at all automatically.
- `days`: array<string> (required) — An array of 3-letter words that define days to ask, example ['Mon', 'Wed', 'Fri'].
- `questions`: array<object> — List of standup questions, an array of objects containing a "question" property. If ommited, 3 Geekbot recommended questions will be used.
- `users`: array<number> (required) — Array of user ids that will be included in the standup.
- `sync_channel_members`: boolean (required) — Standup participants will be synced with channel members.
- `personalised`: boolean (required) — Allow users to change their personal schedule for the standup

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts (HH:MM:SS).
  - `wait_time`: number — Minutes to wait after login before asking (-1 = no automatic asking).
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — Days when standup is active.
  - `channel`: string — Channel where standup updates are posted.
  - `questions`: array<object> — Standup questions.
  - `users`: array<object> — Standup participants.
  - `sync_channel_members`: boolean — Whether participants are synced from the channel.

#### GET /v1/standups/{id} — Get standup

Returns a standup by ID. The standup must belong to the authenticated team, and the authenticated user must be a participant or the standup creator.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Standup unique id. |

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts.
  - `wait_time`: number — Minutes to wait after user logs in before asking a question. Null value means no automated asking.
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — List of days when standup is active.
  - `channel`: string — Channel where the standup updates are posted.
  - `questions`: array<object> — List of standup questions.
  - `users`: array<object> — List of users taking part in the standup.
  - `sync_channel_members`: boolean — Standup participants will be synced with channel members.

#### DELETE /v1/standups/{id} — Delete standup

Deletes a standup. The authenticated user must have permission to edit it.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Standup unique id. |

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts (HH:MM:SS).
  - `wait_time`: number — Minutes to wait after login before asking (-1 = no automatic asking).
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — Days when standup is active.
  - `channel`: string — Channel where standup updates are posted.
  - `questions`: array<object> — Standup questions.
  - `users`: array<object> — Standup participants.
  - `sync_channel_members`: boolean — Whether participants are synced from the channel.

#### PATCH /v1/standups/{id} — Update standup

Updates one or more standup fields. Only properties included in the request body are changed.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Standup unique id. |

**Request body** (`application/json`)

- `channel`: string — Channel where the standup updates are posted.
- `name`: string — Standup name.
- `time`: string — Time to ask standup in HHMM format.
- `timezone`: string — Timezone to use when calculating time to ask.
- `wait_time`: number (required) — Minutes to wait after team member is online before asking a question. Set to null so that users do not get asked at all automatically.
- `days`: array<string> — An array of 3-letter words that define days to ask, example ['Mon', 'Wed', 'Fri']
- `questions`: array<object> — List of standup questions, an array of objects containing a "question" property.
- `users`: array<number> — Array of user ids that will be included in the standup.
- `sync_channel_members`: boolean (required) — Standup participants will be synced with channel members. If this is set to "false" you need to provide the "users" parameter.
- `personalised`: boolean (required) — Allow users to change their personal schedule for the standup

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts (HH:MM:SS).
  - `wait_time`: number — Minutes to wait after login before asking (-1 = no automatic asking).
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — Days when standup is active.
  - `channel`: string — Channel where standup updates are posted.
  - `questions`: array<object> — Standup questions.
  - `users`: array<object> — Standup participants.
  - `sync_channel_members`: boolean — Whether participants are synced from the channel.

#### PUT /v1/standups/{id} — Replace standup

Replaces an existing standup configuration with the provided payload. All required fields must be included, and the authenticated user must have permission to edit the standup.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Standup unique id. |

**Request body** (`application/json`)

- `channel`: string (required) — Channel where the standup updates are posted.
- `name`: string (required) — Standup name.
- `time`: string (required) — Time to ask standup in HHMM format.
- `timezone`: string (required) — Timezone to use when calculating time to ask. If not specified, default is user local.
- `wait_time`: number (required) — Minutes to wait after team member is online before asking a question. Set to null so that users do not get asked at all automatically.
- `days`: array<string> (required) — An array of 3-letter words that define days to ask, example ['Mon', 'Wed', 'Fri']
- `questions`: array<object> — List of standup questions, an array of objects containing a "question" property. If ommited, 3 Geekbot recommended questions will be used.
- `users`: array<number> (required) — Array of user ids that will be included in the standup.
- `sync_channel_members`: boolean (required) — Standup participants will be synced with channel members. If this is set to "false" you need to provide the "users" parameter.

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts (HH:MM:SS).
  - `wait_time`: number — Minutes to wait after login before asking (-1 = no automatic asking).
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — Days when standup is active.
  - `channel`: string — Channel where standup updates are posted.
  - `questions`: array<object> — Standup questions.
  - `users`: array<object> — Standup participants.
  - `sync_channel_members`: boolean — Whether participants are synced from the channel.

#### POST /v1/standups/{id}/duplicate — Duplicate standup

Creates a new standup by duplicating an existing one. Any fields provided in the request body override the copied configuration.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | string |  |

**Request body** (`application/json`)

- `name`: string (required) — Standup name (required).
- `channel`: string (required) — Channel where the standup updates are posted.
- `time`: string (required) — Time to ask standup in "HH:MM:SS" format.
- `timezone`: string (required) — Timezone to use when calculating time to ask. If not specified, default is user local.
- `wait_time`: number — Minutes to wait after team member is online before asking a question. Set to null so that users do not get asked at all automatically.
- `days`: array<string> (required) — An array of 3-letter words that define days to ask, example ['Mon', 'Wed', 'Fri'].
- `questions`: array<object> — List of standup questions, an array of objects containing a "question" property. If ommited, 3 Geekbot recommended questions will be used.
- `users`: array<number> (required) — Array of user ids that will be included in the standup.
- `sync_channel_members`: boolean (required) — Standup participants will be synced with channel members..
- `personalised`: boolean (required) — Allow users to change their personal schedule for the standup

**Responses**

- `200` — Success
  - `id`: number — Standup unique id.
  - `name`: string — Standup name.
  - `time`: string — Time standup starts (HH:MM:SS).
  - `wait_time`: number — Minutes to wait after login before asking (-1 = no automatic asking).
  - `timezone`: string — Timezone used to calculate standup time.
  - `days`: array<string> — Days when standup is active.
  - `channel`: string — Channel where standup updates are posted.
  - `questions`: array<object> — Standup questions.
  - `users`: array<object> — Standup participants.
  - `sync_channel_members`: boolean — Whether participants are synced from the channel.

#### POST /v1/standups/{id}/start — Start standup

Starts a standup immediately. If `users` or `emails` are provided, the standup runs only for those participants.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | number | Standup unique id. |

**Request body** (`application/json`)

- `users`: array<string> (required) — Array of user ids that will be included in the standup.
- `emails`: array<string> (required) — Array of user emails that will be included in the standup.

**Responses**

- `200` — Success