canonical: https://jentic.com/apis/flow.team/flow-team

# flow.team API

Jentic publishes the only available OpenAPI specification for flow.team API, keeping it validated and agent-ready. flow.team is a team collaboration platform that organizes work around chats, posts, projects, and divisions. The API exposes endpoints for managing bots, posting messages to chats, listing employees and divisions, creating projects, and authenticating users via SSO. Authentication uses an x-flow-api-key header on every request.

## For AI agents

Post messages to flow.team chats, manage bots and projects, look up employees and divisions, and authenticate users via SSO from agent workflows.

## Scope

Does not handle external email, video conferencing, or document storage - use for flow.team chat, bot, employee, and project operations only.

## Capabilities

- Create and manage bots that post automated updates into flow.team chats
- Send posts and messages to specific chats on behalf of users or bots
- List employees and assign them to divisions or projects
- Create and update projects to organize team work
- Authenticate users into flow.team via the SSO endpoint
- Look up division structures to route messages to the right team
- Retrieve chat metadata to verify membership before posting

## Use cases

### Bot-Driven Chat Notifications

Wire automated systems into flow.team chats by registering a bot via `/v1/bots` and posting structured messages through `/v1/posts.` Useful for piping deploy events, ticket updates, and on-call alerts into the right team channel without manual relays. Setup takes a few hours including bot registration, channel mapping, and message templating.

Example prompt: Register a bot named 'deploy-bot' via `/v1/bots` and post a message containing the latest deployment status to the engineering chat.

### Employee and Division Lookup

Query the `/v1/employees` and `/v1/divisions` endpoints to resolve users to their division, role, and contact details. This supports HR-style automations such as routing requests to the right manager or generating org-chart snapshots. The `/v2/employees` endpoint returns an extended payload with richer profile fields.

Example prompt: Call `/v2/employees` to retrieve all employees in the 'Sales' division and return their names and email addresses.

### Project Coordination

Create projects through `/v1/projects` and tie them to specific divisions and employees, then track status as the work progresses. Suits agent flows that spin up project records when a deal is won or a ticket is escalated. Records are scoped per tenant and retrievable by project ID.

Example prompt: Create a new project titled 'Q3 Launch Prep' under the 'Marketing' division and assign three named employees to it.

### AI Agent Integration via Jentic

Agents discover the flow.team operations through Jentic's intent search, load the schema for the post creation endpoint, and execute calls without ever holding the raw x-flow-api-key. This is the recommended path for embedding flow.team chat output into LangChain, CrewAI, or MCP-based assistants. Agents stay scoped to the operations they need.

Example prompt: Use Jentic to search 'post a message to a flow.team chat', load the `/v1/posts` schema, and send a notification to a specified chat ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/chats` | List chats accessible to the caller |
| POST | `/v1/posts` | Create a post inside a chat |
| GET | `/v1/employees` | List employees in the tenant |
| GET | `/v2/employees` | List employees with extended profile fields |
| GET | `/v1/divisions` | List divisions |
| POST | `/v1/bots` | Register a new bot |
| GET | `/v1/projects` | List projects |
| GET | `/v1/sso` | Initiate an SSO sign-in flow |

## Key resources

- **Bots** — Register and manage bots that post automated content into flow.team chats.
- **Chats** — List chats and retrieve chat metadata for routing messages.
- **Posts** — Create posts and messages inside chats.
- **Divisions** — List and inspect divisions used to organize employees.
- **Employees** — Look up employee profiles via v1 and v2 endpoints.
- **Projects** — Create and manage projects associated with divisions and employees.
- **SSO** — Initiate single sign-on flows for users entering a flow.team tenant.

## Why Jentic

- **Setup:** Wiring the flow.team API by hand means setting the x-flow-api-key header on every call, tracking the split between its v1 and v2 employee endpoints, and building your own retry and error handling. Through Jentic you install once, import flow.team from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** flow.team carries the chat, post, and project 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 listing chats or creating a post, and leave out bot creation or employee lookups unless you add them. Every operation the agent can run is one you chose.
- **Credential handling:** Your flow.team x-flow-api-key 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 'post a message to a flow.team chat', and Jentic returns the matching `/v1/posts` operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Slack API** — Mainstream team chat platform with a much larger surface area than flow.team.
- **Mattermost API** — Self-hosted team messaging alternative for organizations that need on-prem control.
- **Asana API** — Task and project tracking that pairs with flow.team chat-based coordination.

## FAQ

### Why is there no official OpenAPI spec for flow.team API?

flow.team does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call flow.team 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 flow.team API use?

The flow.team API uses an API key passed in the x-flow-api-key header on every request. Jentic stores the key encrypted in your Jentic One instance and injects it into outgoing calls so the agent never sees the raw secret.

### Can I post messages to a chat with the flow.team API?

Yes, the `/v1/posts` endpoint creates a post inside a chat referenced by chat ID, and `/v1/chats` lists available chats so you can resolve the right ID before sending.

### What are the rate limits for the flow.team API?

The OpenAPI spec does not declare explicit rate limits. Apply client-side throttling for high-volume bot traffic and check the response headers for any 429 responses returned by the live service.

### How do I list employees in a division through Jentic?

Search Jentic for 'list flow.team employees', load the `/v2/employees` schema, and execute the call with the division identifier as a query parameter. The richer v2 payload returns profile fields the v1 endpoint omits.

### Does the flow.team API support SSO flows?

Yes, the `/v1/sso` endpoint initiates a single sign-on session for a tenant. Use it to redirect users into authenticated flow.team sessions from your own application.

### Can I limit what my agent is allowed to do with the flow.team API?

Yes. Because Jentic One is self-hosted, you set the rules for which flow.team operations your agent may call, so you can allow it to list chats and create a post while leaving out registering bots or looking up employees, divisions, and projects. flow.team carries the chat, post, and project targets in the request body rather than the URL, so scoping is operations-only: every operation the agent can run is one you chose to enable. Your x-flow-api-key stays stored in your own instance and is injected only for the operations you permit.