canonical: https://jentic.com/apis/flock.com/flock

# Flock API

The Flock API exposes the team-messaging surface of the Flock workplace chat platform. It uses FlockOS-style methods accessed through POST requests with a query-parameter token, covering channels, chat messages, contacts, and user profiles. The API supports sending messages, fetching message history, creating channels, and managing channel membership.

## For AI agents

Send messages, fetch chat history, create channels, manage channel membership, and look up users on the Flock team-messaging platform.

## Scope

Does not handle voice or video calls, file sharing, or external email - use for Flock channel and direct messaging, channel management, and user lookups only.

## Capabilities

- Send a chat message to a Flock channel or direct user
- Fetch the recent message history of a channel for analysis or display
- Create a new channel with a name and a list of initial members
- Add or remove members from an existing channel
- List the members of a channel for audit and notification flows
- Look up a user's profile or public profile by user ID

## Use cases

### Workflow notifications into team channels

Internal tools and automations call /chat.sendMessage to post structured updates into Flock channels - deployment notices, alert summaries, or daily digest messages. The same endpoint handles both channel and direct messages, so a single integration covers personal and team notifications.

Example prompt: Send a deployment-success message with the build ID to channel #engineering

### Channel and membership management

HR and ops tools create per-project channels, seed them with the right members, and clean up when the project ends. /channels.create, /channels.addMembers, and /channels.removeMembers cover the full lifecycle, while /channels.listMembers backs audit dashboards that confirm who currently has access to each space.

Example prompt: Create channel #project-launch and add five named user IDs as members

### Conversation history analysis

Analytics and search tools call /chat.fetchMessages to pull recent message history for a channel and feed it into summarisation, search, or compliance pipelines. Combined with /users.getInfo and /roster.listContacts, the API provides enough context to attribute each message to a named team member.

Example prompt: Fetch the last 100 messages from channel C123 and resolve each sender ID to a display name

### AI agent team assistant

An AI assistant uses Flock through Jentic to answer natural-language requests such as 'summarise the engineering channel today' or 'invite Alice to the launch channel'. Jentic returns the right Flock method per intent so the agent does not need to learn the FlockOS POST-with-query-token convention before issuing calls.

Example prompt: Fetch today's messages from channel C123, summarise them, and post the summary back into the same channel

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/chat.sendMessage` | Send a message to a channel or user |
| POST | `/chat.fetchMessages` | Fetch recent messages from a channel |
| POST | `/channels.list` | List channels accessible to the token |
| POST | `/channels.create` | Create a new channel |
| POST | `/channels.addMembers` | Add members to a channel |
| POST | `/channels.removeMembers` | Remove members from a channel |
| POST | `/users.getInfo` | Look up a user's profile information |

## Key resources

- **Chat** — Send messages to channels or users, and fetch message history
- **Channels** — Create channels, list members, and add or remove members
- **Contacts** — List the authenticated user's contact roster
- **Users** — Look up user info and public profiles by user ID

## Why Jentic

- **Setup:** Wiring the Flock API by hand means handling its unusual apiKey-in-query-parameter scheme, where the token rides in the URL on every POST, and building your own retry and error handling around the FlockOS methods. Through Jentic you install once, import Flock from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Flock passes the channel and message targets in the request body rather than the URL path, so scoping is operations-only: you limit the agent to the operations it needs, such as sendMessage or fetchMessages, and leave out channel creation or member removal unless you add them. Every operation the agent can run is one you explicitly chose.
- **Credential handling:** Your Flock 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 'send a message to a Flock channel' or 'list channels', and Jentic returns the matching FlockOS method with its input schema so the agent calls the right endpoint without learning the POST-with-query-token convention from the reference docs.

## Related APIs

- **Slack Web API** — Slack is the dominant team-messaging API with a much larger surface than Flock
- **Discord API** — Discord is community-focused chat that overlaps with Flock for messaging primitives
- **Mattermost API** — Mattermost is a self-hosted alternative for team messaging

## FAQ

### What authentication does the Flock API use?

The Flock API uses an API token passed as a 'token' query parameter on each POST request. Through Jentic the token is held in the encrypted vault and appended at execution time, so the raw token never enters the agent context.

### Can I send a message to a channel with the Flock API?

Yes. POST to /chat.sendMessage with the channel ID and message text. The same endpoint handles direct messages by passing a user ID instead of a channel ID.

### How do I create a new Flock channel and add members?

Call POST /channels.create with the channel name to create the channel, then POST /channels.addMembers with the channel ID and an array of user IDs to seed it with the right members.

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

Flock does not document a fixed global rate limit in the spec. Limits are applied per token. Treat 429 responses as the source of truth and back off using the Retry-After header.

### How do I post a Flock message through Jentic?

Search Jentic for 'send a Flock message', load the schema for /chat.sendMessage, and execute the call with the channel ID and text. Install with pip install jentic and run it through Jentic One, the self-hosted execution layer.

### Can I fetch message history with this API?

Yes. POST to /chat.fetchMessages with a channel ID and pagination cursor to retrieve recent messages.

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

Yes. Because you run Jentic One yourself, your own rules decide which Flock operations and which stored token the agent may use. Flock takes its channel and message targets in the request body rather than the URL, so scoping is operations-only: you can allow read and send operations like /chat.fetchMessages and /chat.sendMessage while withholding /channels.create and /channels.removeMembers. Every operation the agent can run is one you explicitly granted.