REST API Version 2
Circuit REST API to interact with the Circuit system. [Learn more about the Circuit Development Community](https://www.circuit.com/web/developers/home)
Communication#openapi#messaging
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Circuit REST API to interact with the Circuit system.
Endpoints 123
Conversations
- GETGets a list of conversations
/conversations?modTime=2024-01-01T00:00:00Z&direction=BEFORE&results=25Gets a list of conversations and communities the authenticated user participates in. OauthScopes: READ_CONVERSATIONS - GETGets conversations
/conversations/byIds?convIds=stringGets conversation based on the given IDs. OauthScopes: READ_CONVERSATIONS - GETGets a list of communities
/conversations/community?sort=ALPHABETICALLY&order=ASCENDING&includeOwn=false&startIndex=0&results=25Gets a list of communities. This endpoint can be used to explore the communities the authenticated user could join. OauthScopes: READ_CONVERSATIONS - POSTCreates a community conversation
/conversations/communityCreates a community. Communities are open conversations that anyone in a Circuit domain (tenant) can join without having to be added by another user.… - PUTUpdates the information of a community
/conversations/community/:convIdUpdates the information of the given community. OauthScopes: WRITE_CONVERSATIONS, MANAGE_CONVERSATIONS - POSTAdds the authenticated user to a community
/conversations/community/:convId/joinAdds the authenticated user to the given community (i.e., allows the user to join this community). Contrary to the operation of adding a new participant, this… - POSTAdds participants to a community
/conversations/community/:convId/participantsAdds one or more participants to the given community. This operation can only be performed by a user who is already a member of the community. OauthScopes:… - DELETERemoves participants from a community
/conversations/community/:convId/participants?participants=stringRemoves one or more participants from the given community. The last participant of a community cannot be removed. This operation can only be performed by a… - GETGets the conference details for multiple conversations
/conversations/conversationdetails?convIds=stringGets the conference details of the given conversations. Conference details include the URL, which is used to join the conference through a web or mobile… - GETChecks for a 1-to-1 conversation
/conversations/direct?participant=stringChecks if a 1-to-1 conversation between the authenticated user and the user with the provided userId exists. OauthScopes: READ_CONVERSATIONS - POSTCreates a 1-to-1 conversation
/conversations/directCreates a 1-to-1 conversation between the authenticated user and the user with the provided userId. In case there is already an existing 1-to-1 conversation… - GETGets favorite conversations
/conversations/favoriteGets the conversationIds which are marked as favorites. OauthScopes: READ_CONVERSATIONS - POSTCreates a group conversation
/conversations/groupCreates a group conversation between three or more users. The authenticated user is directly added to this conversation. OauthScopes: WRITE_CONVERSATIONS,… - PUTUpdates the information of a group conversation
/conversations/group/:convIdUpdates the information of the given group conversation. OauthScopes: WRITE_CONVERSATIONS, MANAGE_CONVERSATIONS - POSTAdds participants to a group conversation
/conversations/group/:convId/participantsAdds one or more participants to the given group conversation. This operation can only be performed by a user who is already a member of the conversation.… - DELETERemoves participants from a group conversation
/conversations/group/:convId/participants?participants=stringRemoves one or more participants from the given group conversation. The last participant of a group conversation cannot be removed. This operation can only be… - GETReturns conversations with a certain label
/conversations/label/:labelId?nextPagePointer=string&pageSize=25Returns conversations with matching labels and paginated OauthScopes: READ_CONVERSATIONS - GETGets a list of the flagged messages
/conversations/messages/flagGets a list of all the messages the authenticated user has flagged. This endpoint should be used carefully in case where the authenticated user has a lot of… - GETReturns a text item
/conversations/messages/:itemIdReturns a text item for a given item id OauthScopes: READ_CONVERSATIONS - POSTSet conversation moderated
/conversations/moderate/:convIdSet a conversation in moderatd mode. Moderators can be added and removed OauthScopes: WRITE_CONVERSATIONS, MODERATE_CONVERSATIONS - GETResolves an invite token to a conversation
/conversations/resolveinvitetoken?token=stringResolves an invite token to a conversation OauthScopes: READ_CONVERSATIONS - GETPerforms a conversation search
/conversations/search?term=string&includeItemIds=false&scope=ALLPerforms a search for conversation content. A maximum of 100 conversations is returned. If you hit this limit you should refine the search term. OauthScopes:… - POSTSet conversation unmoderated
/conversations/unmoderate/:convIdSet a conversation to unmoderatd mode OauthScopes: WRITE_CONVERSATIONS, MODERATE_CONVERSATIONS - GETGets a conversation
/conversations/:convIdGets a conversation based on the given ID. OauthScopes: READ_CONVERSATIONS - POSTArchives conversation
/conversations/:convId/archiveArchives a conversation by muting it OauthScopes: WRITE_CONVERSATIONS - DELETEUnmute conversation
/conversations/:convId/archiveThe conversation will no longer be archived but active again OauthScopes: WRITE_CONVERSATIONS - GETGets the conference details of a conversation
/conversations/:convId/conversationdetailsGets the conference details of the given conversation. Conference details include the URL, which is used to join the conference through a web or mobile… - POSTAdds a conversation to the favorites
/conversations/:convId/favoriteAdds a conversation to the favorites. Favorites can be displayed in a separate side tab inside of the Circuit client to have a better overview of important… - DELETERemoves a conversation from favorites
/conversations/:convId/favoriteRemoves a conversation from favorites. Favorites can be displayed in a separate side tab inside of the Circuit client to have a better overview of important… - GETGets a list of conversation items
/conversations/:convId/items?modTime=2024-01-01T00:00:00Z&direction=BEFORE&results=25Gets a list of conversation items. OauthScopes: READ_CONVERSATIONS - POSTAdds a label to a conversation
/conversations/:convId/labelAdds a label to a conversation, you can search and organize your conversations based on these labels OauthScopes: WRITE_CONVERSATIONS, ORGANIZE_CONVERSATIONS - DELETERemoves a label from a conversation
/conversations/:convId/label/:labelIdRemoves a label from a conversation, you can search and organize your conversations based on these labels OauthScopes: WRITE_CONVERSATIONS - POSTAdds a message to a conversation
/conversations/:convId/messagesAdds a message to the given conversation. This operation can be only performed on behalf of a user who is already a member of the conversation. OauthScopes:… - GETGets a list of the flagged messages of a conversation
/conversations/:convId/messages/flagGets a list of all the flagged messages in the given conversation. OauthScopes: READ_CONVERSATIONS, ORGANIZE_CONVERSATIONS - PUTUpdates a message
/conversations/:convId/messages/:itemIdUpdates the content or subject of the existing message. Only the creator of the message is allowed to perform this operation. OauthScopes:… - POSTAdds a message to an item
/conversations/:convId/messages/:itemIdAdds a message to the existing item. The added message will be a child item of the message with the given itemId. OauthScopes: WRITE_CONVERSATIONS - DELETEDeletes a message from a conversation
/conversations/:convId/messages/:itemIdMarks a message in the given conversation as deleted. Deleted messages are still part of the conversation, but their content is no more visible. This… - POSTAdds a flag to a message in a conversation
/conversations/:convId/messages/:itemId/flagAdds a flag to the given message in the given conversation. OauthScopes: WRITE_CONVERSATIONS, ORGANIZE_CONVERSATIONS - DELETERemoves the flag from a message
/conversations/:convId/messages/:itemId/flagRemoves the flag from a given message that is posted to the given conversation. OauthScopes: WRITE_CONVERSATIONS, ORGANIZE_CONVERSATIONS - POSTAdds a "like" to a message
/conversations/:convId/messages/:itemId/likeAdds a "like" to the given message in the given conversation OauthScopes: WRITE_CONVERSATIONS, UPDATE_CONVERSATION_CONTENT - DELETERemoves a "like" from a message
/conversations/:convId/messages/:itemId/likeRemoves a "like" from the given message in the given conversation OauthScopes: WRITE_CONVERSATIONS, UPDATE_CONVERSATION_CONTENT - POSTAdd moderators
/conversations/:convId/moderatorsAdds a list of moderators to a conversation OauthScopes: WRITE_CONVERSATIONS, MANAGE_CONVERSATIONS - DELETERemove moderators
/conversations/:convId/moderatorsRemoves a list of moderators from a conversation OauthScopes: WRITE_CONVERSATIONS, MODERATE_CONVERSATIONS - GETPerforms a list of participants
/conversations/:convId/participants?pageSize=1.0&name=string&type=REGULAR&searchPointer=stringPerforms a search for participants. The max number of participants is configurable. If more participants are available a search pointer is returned for… - GETReturns pinned topics of a conversation
/conversations/:convId/pinsReturns pinned topics of a conversation OauthScopes: READ_CONVERSATIONS - POSTPins a topic of a conversation
/conversations/:convId/pins/:itemIdPins a topic of a conversation OauthScopes: READ_CONVERSATIONS - DELETEUnpins a topic of a conversation
/conversations/:convId/pins/:itemIdUnpins a topic of a conversation OauthScopes: READ_CONVERSATIONS - POSTAdd a user label
/users/labelsAdd a label to the list of user labels OauthScopes: WRITE_USER_PROFILE, ORGANIZE_CONVERSATIONS - DELETERemove a user label
/users/labels/:labelIdRemove a label from the list of user labels OauthScopes: WRITE_USER_PROFILE, ORGANIZE_CONVERSATIONS - PUTUpdates the user profile
/users/profileUpdates the user profile of the authenticated user OauthScopes: WRITE_USER_PROFILE
RTC
- GETGets a list of active sessions
/rtc/sessionsGets a list of active RTCsessions OauthScopes: CALLS
Spaces
- GETGet the spaces
/spaces?timestamp=2024-01-01T00:00:00Z&numberOfResults=0.0Get the spaces OauthScopes: READ_SPACE - POSTCreate a space
/spaces/createCreate a space OauthScopes: WRITE_SPACE, MANAGE_SPACE, CREATE_SPACE_CONTENT - GETGet the directory
/spaces/directory?sortBy=LAST_CONTENT&sortOrder=ASCENDING&filter=NONE&query=string&pagePointer=string&numberOfResults=25Get the directory by a search query in ordered way OauthScopes: READ_SPACE - GETSpace name exists
/spaces/exists/:nameFind out if a space name already exists for non-secret spaces. OauthScopes: READ_SPACE - PUTflag a space item
/spaces/flag/:itemIdflag a space item OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - GETGet flagged items
/spaces/flagged?searchDirection=BEFORE×tamp=2024-01-01T00:00:00Z&searchPointer=string&numberOfResults=25Get flagged items OauthScopes: READ_SPACE - GETGet the spaces by their ids
/spaces/ids?ids=stringGet the spaces by their ids OauthScopes: READ_SPACE - DELETEdeletes a space item
/spaces/item/:itemIddeletes a space item OauthScopes: WRITE_SPACE, DELETE_SPACE_CONTENT - PUTLike a space item
/spaces/like/:itemIdLike a space item OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - GETGet the likes of an item
/spaces/likes/:itemId?searchPointer=string&numberOfResults=25Get the likes of an item OauthScopes: READ_SPACE - PUTAdd recent search
/spaces/search/add/recentAdd recent search of a client to search controller. OauthScopes: WRITE_SPACE, MANAGE_SPACE, ORGANIZE_SPACE - PUTCancels a space search of a client.
/spaces/search/cancel/:searchIdCancels a space search of a client. OauthScopes: WRITE_SPACE, MANAGE_SPACE - GETRetrieve recent space searches
/spaces/search/recentRetrieve recent space searches for a user. OauthScopes: READ_SPACE - GETstarts a basic search in spaces
/spaces/search/startBasic?scope=ALL&searchTerm=string&startTime=2024-01-01T00:00:00Z&endTime=2024-01-01T00:00:00Z&prioritySpaces=stringstarts a basic search in spaces OauthScopes: READ_SPACE - GETstarts a detailed search in a space
/spaces/search/startDetailed?scope=ALL&searchTerm=string&startTime=2024-01-01T00:00:00Z&endTime=2024-01-01T00:00:00Z&spaceId=string&searchId=stringstarts a detailed search in a space OauthScopes: READ_SPACE - PUTUpdate tags
/spaces/topic/:topicId/updateTagsUpdate the tags of a topic OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - PUTUnflag a space item
/spaces/unflag/:itemIdUnflag a space item OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - PUTUnlike a space item
/spaces/unlike/:itemIdUnlike a space item OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - PUTUpdate a space
/spaces/:idUpdate a space OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - DELETEDelete a space
/spaces/:idDelete a space OauthScopes: WRITE_SPACE, MANAGE_SPACE, DELETE_SPACE_CONTENT - POSTJoin a space
/spaces/:id/joinJoin a space OauthScopes: WRITE_SPACE - POSTAssign labels
/spaces/:id/labels/assignAssign labels to space OauthScopes: WRITE_SPACE, ORGANIZE_SPACE - DELETEUnassign labels
/spaces/:id/labels/unassignUnassign labels from a space OauthScopes: WRITE_SPACE, ORGANIZE_SPACE - POSTLeave a space
/spaces/:id/leaveLeave a space OauthScopes: WRITE_SPACE - POSTAdd Participant to Space
/spaces/:id/participantAdd a participant to a space OauthScopes: WRITE_SPACE, MANAGE_SPACE - POSTRemoves participants from a space
/spaces/:id/participant/removeremoves Participants from a space OauthScopes: WRITE_SPACE, MANAGE_SPACE, ORGANIZE_SPACE - GETGet the participants of a space
/spaces/:id/participants?sortBy=NAME&sortOrder=ASCENDING&filterType=NONE&filterValue=string&query=string&searchPointer=string&numberOfResults=25Get the participants of a space OauthScopes: READ_SPACE - GETGet the pending participants of a space
/spaces/:id/participants/pending?searchPointer=string&numberOfResults=25Get the pending participants of a space OauthScopes: WRITE_SPACE, MANAGE_SPACE - GETRetrieve pinned topics
/spaces/:id/pinnedTopicsRetrieve pinned topics of a space OauthScopes: READ_SPACE - GETFinds participants to add to add to a space
/spaces/:id/searchParticipantsToAdd?query=stringFinds participants to add to a space OauthScopes: WRITE_SPACE, MANAGE_SPACE, ORGANIZE_SPACE - GETGet the participants of a space
/spaces/:id/searchSpaceParticipants?query=stringGet the participants of a space OauthScopes: READ_SPACE - PUTUpdate read timestamp
/spaces/:id/updateTimestampUpdate read timestamp OauthScopes: READ_SPACE, WRITE_SPACE - PUTUpdate participant
/spaces/:spaceId/participantUpdate participant in space OauthScopes: WRITE_SPACE, MANAGE_SPACE, ORGANIZE_SPACE - GETmissing documentation
/spaces/:spaceId/participant/import/missing documentation OauthScopes: READ_SPACE - POSTrequest access for a space
/spaces/:spaceId/participant/requestrequest access for a space OauthScopes: READ_SPACE - POSTDeny access for a space
/spaces/:spaceId/participant/:participantId/denyDeny access for a space OauthScopes: WRITE_SPACE, MANAGE_SPACE - POSTgrant access for a space
/spaces/:spaceId/participant/:participantId/grantgrant access for a space OauthScopes: WRITE_SPACE, MANAGE_SPACE - POSTcreates a new space topic
/spaces/:spaceId/topiccreates a new space topic OauthScopes: WRITE_SPACE, MANAGE_SPACE, CREATE_SPACE_CONTENT - GETGets space replies and a topic
/spaces/:spaceId/topic/:topicId?numberOfReplies=25Gets a number of Space replies with a matching topic OauthScopes: READ_SPACE - PUTUpdates a topic
/spaces/:spaceId/topic/:topicIdUpdates a topic OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - GETGets space replies
/spaces/:spaceId/topic/:topicId/reply?searchDirection=BEFORE×tamp=2024-01-01T00:00:00Z&numberOfResults=25Gets a number of Space replies OauthScopes: READ_SPACE - POSTcreates a reply to a topic
/spaces/:spaceId/topic/:topicId/replycreates a reply to a topic OauthScopes: WRITE_SPACE - PUTUpdates a space reply
/spaces/:spaceId/topic/:topicId/reply/:replyIdUpdates a space reply OauthScopes: WRITE_SPACE, UPDATE_SPACE_CONTENT - GETGets space topics
/spaces/:spaceId/topics?searchDirection=BEFORE×tamp=2024-01-01T00:00:00Z&numberOfResults=25Gets a number of Space topics OauthScopes: READ_SPACE - PUTUpdate content of welcome box
/spaces/:spaceId/welcomebox/:contentUpdate content of the welcome box of a space OauthScopes: MANAGE_SPACE, WRITE_SPACE - PUTPin a topic
/spaces/:topicId/pinPin a topic OauthScopes: WRITE_SPACE, MANAGE_SPACE - PUTUnpin a topic
/spaces/:topicId/unpinUnpin a topic OauthScopes: WRITE_SPACE, MANAGE_SPACE
Telephony
- GETGet devices infos
/telephony/deviceInfosGet the device infos of the requesting user OauthScopes: READ_USER_PROFILE - GETGet telephony conversation id
/telephony/telephonyConversationIdGet telephony conversation id for requesting client OauthScopes: READ_CONVERSATIONS - GETGet journal
/telephony/:telephonyConversationId/journal?timestamp=0&numberOfEntries=25&direction=AFTER&journalFilter=ALLGet telephony journal OauthScopes: READ_CONVERSATIONS
Users
- GETSearch for users
/users?name=stringSearch for users based on an email address or username OauthScopes: READ_USER - GETReturns all user labels
/users/labelsReturns all labels of the user that were defined either explicit or implicit via assignment to conversations. OauthScopes: READ_USER_PROFILE,… - GETSearch multiple users.
/users/list?name=string&returnFullUserInfo=false&secondaryLookup=falseSearch multiple users given by id or email address. OauthScopes: READ_USER - GETGets the presence status
/users/presence?userIds=stringGets the presence status of the users whose IDs or email addresses are given. OauthScopes: READ_USER - PUTUpdates the presence status
/users/presenceUpdates the presence status of the authenticated user. OauthScopes: WRITE_USER_PROFILE, MANAGE_PRESENCE - GETGets the authenticated user's profile information
/users/profileGets the authenticated user's profile information. OauthScopes: READ_USER_PROFILE - GETGets the support information
/users/supportinfoGets the support information for the tenant of the requesting user OauthScopes: READ_USER_PROFILE - GETGet user by email
/users/:emailAddress/getUserByEmail?secondaryLookup=trueGet user by first or secondary email address OauthScopes: READ_USER_PROFILE - GETGets the user's profile information
/users/:idGets the profile information of the user with the given ID. OauthScopes: READ_USER - GETGets the presence status
/users/:id/presenceGets the presence status of the users whose ID or email address is given. OauthScopes: READ_USER
Outgoing Webhooks
- GETGets a list of webHooks
/webhooksGets the list of webHooks registered for this user or API. OauthScopes: READ_CONVERSATIONS, READ_USER - POSTRegisters a WebHook
/webhooksRegisters the webHook with the given filter and callback URL. OauthScopes: READ_CONVERSATIONS, READ_USER - DELETERemoves all webHooks
/webhooksUnregisters all webHooks of the authenticated user OauthScopes: READ_CONVERSATIONS, READ_USER - POSTRegisters Presence WebHook registration
/webhooks/presenceRegisters a webHook that has a presence filter with the given URL and userIds. There is a maximum number of userIds allowed OauthScopes: READ_USER - PUTUpdates a Presence WebHook registration
/webhooks/presence/:idUpdates a registration of a webHook that has a presence filter. The update can be performed either on the URL and/or the userIds. The new userIds, if any,… - GETGets a webHook
/webhooks/:idGets the registered webHook with the given ID. OauthScopes: READ_CONVERSATIONS, READ_USER - PUTUpdates a WebHook registration
/webhooks/:idUpdates a webHook registration with the given filter and callback URL. OauthScopes: READ_CONVERSATIONS, READ_USER - DELETERemoves a registered webHook
/webhooks/:idUnregisters the webHook with the given ID. OauthScopes: READ_CONVERSATIONS, READ_USER
Incoming Webhooks
- POSTCreate a new webhook for existing conversation.
/webhooks/incoming/create/:conversationId?name=string&userId=string&description=stringCreate a new webhook. Conversation must exist and creater has to be participant. OauthScopes: WRITE_CONVERSATIONS, MANAGE_CONVERSATIONS - GETGet all webhooks of a special user.
/webhooks/incoming/user/:userId?pagesize=25&searchpointer=stringGet all webhooks of a special user. OauthScopes: READ_CONVERSATIONS, MANAGE_CONVERSATIONS - POSTPost text item for conversation via webhook.
/webhooks/incoming/:webhookIdPost text items to conversations via slack apps. - DELETEDelete an existing webhook
/webhooks/incoming/:webhookIdDelete a new webhook. Webhook must exist OauthScopes: WRITE_CONVERSATIONS, MANAGE_CONVERSATIONS
API details
- Base URL
https://circuitsandbox.net/rest/v2- Authentication
- OAuth 2.0 (implicit flow) with 26 scopes
- Operations
- 123 operations on 100 pathsGET 51POST 33PUT 22DELETE 17
- Main resources
- Conversations 50Spaces 47Users 10Outgoing Webhooks 8Incoming Webhooks 4Telephony 3RTC 1
- Response formats
application/jsonapplication/xml*/*- Description format
- OpenAPI 3.0.0, API version
2.9.235 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the REST API Version 2 in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the REST API Version 2 collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (implicit flow) with 26 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Gets a list of conversations” (GET /conversations?modTime=2024-01-01T00:00:00Z&direction=BEFORE&results=25), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the REST API Version 2?
Circuit REST API to interact with the Circuit system. [Learn more about the Circuit Development Community](https://www.circuit.com/web/developers/home) It is listed under Communication and has 123 endpoints.
Who publishes the REST API Version 2?
It is listed from Circuitsandbox's public API description (an OpenAPI document), not published by Circuitsandbox on Swastik Codes. Anyone who controls circuitsandbox.net can claim the profile by adding a DNS TXT record.
What is the base URL of the REST API Version 2?
Requests go to https://circuitsandbox.net/rest/v2. Endpoint paths are added to this base URL.
How do I authenticate with the REST API Version 2?
With OAuth 2.0 (implicit flow) with 26 scopes.
How many endpoints does the REST API Version 2 have?
123 operations on 100 paths (51 GET, 33 POST, 22 PUT, 17 DELETE). The largest groups are Conversations, Spaces, Users, Outgoing Webhooks.
Is forking the REST API Version 2 free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.