canonical: https://jentic.com/apis/circuitsandbox.net/circuitsandbox

# Circuitsandbox Circuit REST API Version 2

Circuit is a team collaboration platform from Unify offering persistent group conversations, direct messages, voice and video calls, screen sharing, and shared spaces. The Circuit REST API v2 exposes 123 endpoints over https://circuitsandbox.net/rest/v2 covering conversations, messages, users, presence, calls, call recording, and spaces. Authentication is OAuth 2.0 implicit flow with fine-grained scopes such as READ_CONVERSATIONS, WRITE_CONVERSATIONS, CALLS, CALL_RECORDING, USER_MANAGEMENT, and MANAGE_PRESENCE so an integration can request only the permissions it actually needs.

## For AI agents

Read and post Circuit conversations, manage users and presence, and start collaboration calls through 123 OAuth-authenticated REST endpoints. Supports community, group, and direct conversations with scope-controlled access.

## Scope

Does not handle billing, CRM, or marketing automation - use for Circuit team conversations, calls, and user management only.

## Capabilities

- Create a community, group, or direct Circuit conversation and add participants
- Search conversations and look up message items by itemId for moderation or audit
- Moderate or unmoderate a conversation by convId to control posting permissions
- Manage user profiles and presence state for the authenticated tenant
- Trigger or join a real-time collaboration call using the CALLS scope
- Archive a Circuit conversation or remove specific participants from a group
- Resolve an invite token to onboard external participants into a community

## Use cases

### Backend Bots Posting Into Circuit Conversations

An ops or build-status bot can authenticate via OAuth 2.0 with the WRITE_CONVERSATIONS scope and post update messages into a Circuit group conversation when CI completes or an alert fires. The /conversations and `/conversations/group` endpoints support creating new threads, while item-level endpoints retrieve and update individual messages.

Example prompt: POST a new Circuit group conversation via `/conversations/group` with a participants list and an initial message body announcing the deploy.

### Conversation Compliance and Search

Administrators can use GET `/conversations/search` and GET `/conversations/messages/flag` to locate flagged content for compliance review, then call POST `/conversations/moderate/{convId}` to restrict posting in problematic threads. The MODERATE_CONVERSATIONS and SEARCH_CONVERSATIONS scopes control these capabilities, so a compliance integration only needs the scopes it actually exercises.

Example prompt: GET `/conversations/search`?searchTerm=invoice and POST `/conversations/moderate/{convId}` for any thread that surfaces sensitive financial content.

### Meeting Hand-off From Chat to Call

When a chat conversation needs to escalate to a live call, an integration can use the CALLS scope to initiate a Circuit call attached to an existing conversation. Combined with CALL_RECORDING for compliance, this lets a workflow promote a discussion thread into a recorded session without users leaving Circuit.

Example prompt: Invoke the Circuit call endpoint to start a real-time session attached to convId 'conv_abc123' with recording enabled.

### AI Agent Daily Standup Summary

An AI agent invoked through Jentic can pull the last 24 hours of messages from a Circuit group via GET `/conversations/{convId}` and the message item endpoints, summarise activity, and post the summary back as a new message. Jentic handles OAuth scope selection so the agent only requests READ_CONVERSATIONS and WRITE_CONVERSATIONS - never USER_MANAGEMENT or CALLS.

Example prompt: Search Jentic for 'summarise yesterday's Circuit conversation', load the GET `/conversations/{convId}` schema, fetch messages, and POST the summary into the same thread.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/conversations` | List conversations for the authenticated user |
| POST | `/conversations/group` | Create a group conversation |
| POST | `/conversations/community` | Create a community conversation |
| GET | `/conversations/search` | Search across conversations |
| POST | `/conversations/moderate/{convId}` | Moderate a conversation |
| GET | `/conversations/{convId}` | Get a conversation by id |
| GET | `/conversations/messages/{itemId}` | Get a specific message item |

## Key resources

- **Conversations** — Community, group, and direct conversation lifecycle and search
- **Messages** — Item-level read, post, flag, and moderation operations
- **Users** — User management, profile, and tenant lookup
- **Presence** — Read and update user presence state
- **Calls and Recording** — Start, join, and record real-time collaboration sessions

## Why Jentic

- **Setup:** Wiring the Circuit REST API by hand means running its OAuth flow and threading conversations, calls, and user management across a large operation surface yourself. Through Jentic you install once, import the Circuit REST API Version 2 from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Circuit puts the conversation id in the URL path (`/conversations/{convId}`), so a rule can pin your agent to a given conversation for reading items and messages. You choose the operations it may call, so moderating or creating conversations is not included unless you add it.
- **Credential handling:** Your Circuit OAuth credential 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 'search team conversations' or 'read messages in a conversation', and Jentic returns the matching Circuit operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cisco API** — Cisco Webex covers the same team-messaging and meeting use cases as Circuit at enterprise scale.
- **GoToMeeting API** — GoToMeeting hosts scheduled meetings that complement Circuit's persistent chat threads.
- **CINNOX API** — CINNOX handles external customer messaging while Circuit handles internal team collaboration.

## FAQ

### What authentication does the Circuit REST API use?

Circuit uses OAuth 2.0 with the implicit flow, with fine-grained scopes including READ_CONVERSATIONS, WRITE_CONVERSATIONS, CALLS, CALL_RECORDING, USER_MANAGEMENT, and MANAGE_PRESENCE. Through Jentic the access token is held in your Jentic One instance and never exposed to the agent.

### Can I post messages into a Circuit conversation programmatically?

Yes. Create or fetch a conversation via `/conversations/group` or `/conversations/{convId}`, then post message items using the item-level endpoints. The WRITE_CONVERSATIONS scope is required for posting.

### What are the rate limits for the Circuit REST API?

Circuit does not document hard rate limits in the OpenAPI spec. Plan for tenant-level throttling and let Jentic surface 429 responses for retry. Circuit recommends batching message reads where possible.

### How do I search Circuit conversations through Jentic?

Run pip install jentic, search Jentic for 'search Circuit conversations', and load GET `/conversations/search.` Supply the search term and execute. Jentic injects the OAuth token at runtime. Get started with Jentic One, the self-hosted execution layer.

### Can I record a Circuit call?

Yes, with the CALL_RECORDING OAuth scope. Combined with the CALLS scope, an integration can start a recorded session attached to a conversation. Recording must comply with your tenant policy and applicable regulation.

### How do I moderate a Circuit conversation?

POST `/conversations/moderate/{convId}` restricts posting to moderators, and POST `/conversations/unmoderate/{convId}` reverses the change. The MODERATE_CONVERSATIONS scope is required and these endpoints typically pair with `/conversations/search` for compliance workflows.

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

Yes. Jentic One is self-hosted, so your own rules decide which Circuit operations and OAuth credentials the agent may use. Because Circuit carries the conversation id in the URL path (`/conversations/{convId}`), you can pin the agent to a specific conversation and allow only read operations such as fetching messages and items. Higher-impact operations like POST `/conversations/group` or POST `/conversations/moderate/{convId}` stay off limits unless you explicitly add them.