---
title: "Cheaply poll whether the user's chatrooms have new activity."
method: POST
path: "/v1/check_chatroom_updates"
tags: ["Chatrooms"]
---

# Cheaply poll whether the user's chatrooms have new activity.

`POST /v1/check_chatroom_updates`

## Request

- Base URL: `https://partner.mindupload.app`
- URL: `https://partner.mindupload.app/v1/check_chatroom_updates`
- Auth: API key in header `X-Partner-Key`

Cheap poll endpoint for chatroom freshness. Send each local chatroom id with the last `updated_at` value you saw, or `null` on the first poll. The response echoes one result per requested room in request order, tells you whether the room is still accessible, and returns `has_updates` when you should fetch new messages.

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `username` string, nullable: The end-user's username.
  - `password` string, nullable: The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage.
  - `chatrooms` object[], nullable: Rooms to check. Each entry must include `chatroom_id`; include `known_updated_at` from the previous response, or null/omit it on the first poll.
    - `chatroom_id` string, required: Chatroom id as returned by chatroom operations.
    - `known_updated_at` number, nullable: The last `updated_at` value your client has for this room, or null on the first poll.

## Response `200`

Result envelope — check the success field.

- object
  - `success` boolean: Whether the call succeeded.
  - `error_message` string, nullable: Human-readable reason when success is false.
  - `error_code` string
  - `server_time` number, nullable: Current server timestamp, useful for client-side poll scheduling.
  - `poll_config` object, nullable: Recommended polling cadence for adaptive chatroom polling.
    - `enabled` boolean, required: Whether adaptive chatroom polling is enabled.
    - `hot_seconds` integer, required: Suggested short polling interval while the room is active.
    - `max_seconds` integer, required: Suggested longest polling interval while the room is idle.
    - `hot_window_seconds` integer, required: How long recent activity keeps a room in the hot polling window.
  - `chatrooms` object[], nullable: One freshness result per requested room, in the same order as the request.
    - `chatroom_id` string, required: Chatroom id as returned by chatroom operations.
    - `accessible` boolean, required: Whether the caller can currently read this room.
    - `updated_at` number, nullable, required: Opaque freshness watermark to send back as `known_updated_at` on the next poll.
    - `has_updates` boolean, required: True when the room changed after the supplied `known_updated_at` value.

## Other responses

- `400`: Invalid request payload.
- `401`: Missing or invalid partner key.
- `403`: Partner is not authorized for this operation.
- `429`: Rate limit exceeded — retry later.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mindupload/apis/mind-upload-partner-api.md) · [All operations](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/revisions/0371bdf78533?raw)