canonical: https://jentic.com/apis/gitter.im/gitter

# Gitter Im Gitter API

Jentic publishes the only available OpenAPI specification for Gitter API, keeping it validated and agent-ready. The Gitter API exposes a small set of operations against the Gitter chat platform - listing rooms a user belongs to, fetching room and user records, posting and reading chat messages, and listing the members of a room. Gitter has been migrated to Matrix, but the v1 REST API remains available for legacy chat integrations and bots. Authentication uses Bearer tokens issued from the Gitter developer settings.

## For AI agents

List Gitter rooms a user belongs to, post and read chat messages, and inspect room membership using the v1 REST API.

## Scope

Does not handle voice or video calls, file uploads, or workspace administration - use for Gitter rooms, messages, and member listings only.

## Capabilities

- Fetch the authenticated user record via GET /user
- List the rooms the user belongs to via GET /rooms
- Read the chat-message stream of a room with GET `/rooms/{roomId}/chatMessages`
- Post a new chat message into a room
- List the members of a specific room
- Resolve room metadata by roomId for bot routing

## Use cases

### Build Notification Bot

Post CI build outcomes, deploy notifications, or release announcements into a Gitter room from an existing pipeline. POST `/rooms/{roomId}/chatMessages` accepts a single text body and returns the persisted message id, so the same bot can keep a sent-message log for later editing or audit.

Example prompt: Post the message 'Build #482 passed on main' into the room with id 5d3a4b... and return the new message id

### Channel Activity Digest

Generate a daily digest of activity across the rooms a user belongs to. The agent calls GET /rooms to enumerate memberships, then pages GET `/rooms/{roomId}/chatMessages` with a sinceId per room to summarise new messages without re-fetching old ones.

Example prompt: List the user's rooms, then for each fetch chatMessages where sinceId is yesterday's last id and count messages by sender

### Chat-Driven Support Bot

Run a support bot that watches a Gitter room and responds to questions. The bot polls GET `/rooms/{roomId}/chatMessages`, classifies each message, and posts a reply via POST `/rooms/{roomId}/chatMessages` - useful for legacy open-source projects still hosted on Gitter rather than Matrix.

Example prompt: Poll chatMessages for the project room, identify any message containing 'install', and reply with the documented install command

### AI Agent Chat Replies

Use Jentic to let an AI agent post helpful replies into a Gitter room when triggered by an external event. The agent issues an intent like 'post a message to gitter', Jentic resolves POST `/rooms/{roomId}/chatMessages`, executes it with the Bearer token from the vault, and returns the message URL the user can verify.

Example prompt: Through Jentic, post the message 'Looking into this now' into the support room and return the response id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/user` | Get the authenticated user |
| GET | `/rooms` | List rooms the user belongs to |
| GET | `/rooms/{roomId}` | Fetch a room by id |
| GET | `/rooms/{roomId}/chatMessages` | List chat messages in a room |
| GET | `/rooms/{roomId}/users` | List members of a room |

## Key resources

- **User** — Fetch the authenticated user record
- **Rooms** — List rooms and resolve room metadata by id
- **Messages** — Read and post chat messages within a room
- **Members** — List the members of a room

## Why Jentic

- **Setup:** Wiring Gitter by hand means learning its bearer auth and tracing which room and message endpoints return what across its versioned host. Through Jentic you install once, import the Gitter API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Gitter puts the room id in the URL path (`/rooms/{roomId}/...`), so a rule can pin your agent to one room: it can read that room's messages and members and nothing else. You choose the operations it may call, and since these are read operations the agent lists rooms and messages without any write access unless you add it.
- **Credential handling:** Your Gitter bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list room messages' or 'find my Gitter rooms', and Jentic returns the matching Gitter operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Matrix Client-Server API** — The federated chat protocol that Gitter migrated to
- **Slack Web API** — Workspace chat platform with a far broader API surface and many bot frameworks
- **Discord API** — Community chat platform with rich permissions, threads, and voice
- **Mattermost API** — Self-hosted team chat platform with a stable v4 REST API

## FAQ

### Why is there no official OpenAPI spec for Gitter API?

Gitter does not publish an OpenAPI specification - the platform has migrated to Matrix and the v1 REST docs are HTML only. Jentic generates and maintains this spec so that AI agents and developers can call Gitter API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Gitter API use?

Gitter uses Bearer token authentication. Tokens are issued from the Gitter developer settings page and sent as Authorization: Bearer <token>. Through Jentic the token is held in your Jentic One instance and the raw secret never appears in the agent's prompt context.

### Can I post a chat message with the Gitter API?

Yes. POST `/rooms/{roomId}/chatMessages` accepts a text body and returns the persisted message id, sender, and timestamp. Resolve the roomId first by listing GET /rooms or by calling GET `/rooms/{roomId}` with a known id.

### What are the rate limits for the Gitter API?

Gitter applies a soft per-token cap roughly equivalent to 100 requests per minute per user, with stricter limits on message-posting endpoints to deter spam. There is no public counter; on HTTP 429 back off and retry after a few seconds before resending the request.

### How do I list a user's rooms through Jentic with Gitter?

Search Jentic for 'list gitter rooms', load the GET /rooms schema, and execute against the stored Bearer token. The response is an array of room objects with id, name, uri, and userCount that you can iterate to drive a chat dashboard.

### Is the Gitter API still supported now that Gitter is on Matrix?

Yes for the v1 REST API documented here - it remains live for legacy chat integrations against the Gitter rooms that have been bridged to Matrix. New projects often prefer the Matrix API directly, but the Gitter v1 surface is still functional for posting messages and reading rooms.

### Can I limit what my agent is allowed to do with the Gitter API?

Yes. Because you run Jentic One yourself, your own rules decide which Gitter operations and credentials the agent may use. Since the room id sits in the URL path (`/rooms/{roomId}/...`), you can pin the agent to a single room so it only reads that room's messages via GET `/rooms/{roomId}/chatMessages` and its members via GET `/rooms/{roomId}/users.` You choose the operations it may call, so you can allow read-only access to GET /rooms and GET /user while withholding POST `/rooms/{roomId}/chatMessages` until you grant it.