A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Webex API is how an app or AI agent works with a Webex workspace: posting messages to a space, creating spaces and adding people to them, looking up people, and scheduling meetings. Access is granted through an access token and a set of scopes that decide what each call can read or write, and an agent is limited to the spaces and people that token reaches. Webex can also push events to a webhook URL when something happens, like a message being posted or a person joining a space.
How an app or AI agent connects to Webex determines what it can reach. There is a route for an app that acts on behalf of a Webex user, a route for a bot with its own identity in a space, a hosted server that exposes Webex tools to agents, and an event stream, each governed by the access token behind it and the scopes that token carries.
The REST API answers at https://webexapis.com/v1. It serves a single current version, version 1, and ships dated changes through a developer changelog.
A bot is a Webex account with its own identity that an app posts and acts as inside a space. A bot is added to spaces like a person, and in a group space it only sees messages that mention it.
Webex publishes official Model Context Protocol servers, including a Messaging server and a Meetings server, that let an agent create, edit, and retrieve messages, manage spaces and memberships, and schedule and look up meetings. The overview is at developer.webex.com/mcp.
Webhooks post a registered resource and event, such as a message being created or a membership deleted, to a receiver URL. A secret set on the webhook signs each delivery with an X-Spark-Signature header so the receiver can confirm it came from Webex.
An OAuth integration asks a Webex user to authorize a chosen set of scopes, then acts on that user's behalf with an access token that expires and refreshes. It is the least-privilege route, because each scope is granted or withheld individually.
A bot has its own account and a long-lived access token that carries the full messaging scope set. A bot only reaches the spaces it has been added to, and in a group space only messages that mention it.
A personal access token from the developer portal acts as the signed-in developer with full scopes. It expires after a short period and is intended for testing, not production.
A service app acts on an organization's behalf with admin-level scopes once an administrator authorizes it, using its own credentials rather than a single user's login.
The Webex API is split into areas an agent can act on, like messages, spaces, memberships, people, teams, and meetings. Each area has its own methods and its own scopes, and some return personal data such as people's email addresses and display names.
List, read, create, edit, and delete messages in a space or direct conversation, including text, rich text, and file attachments.
List, read, create, update, and delete spaces, the group and direct conversations that hold messages and people.
List, read, create, update, and delete memberships, the link between a person and a space, which is how people are added to or removed from a conversation.
Read the calling user's own details, look up and list people, and on an admin token create, update, and delete people in the organization.
List, read, create, update, and delete teams, the grouping that ties related spaces together.
List, read, create, update, and delete the memberships that place people in a team.
List, read, create, update, and delete scheduled meetings, and end a meeting that is running.
List, read, create, update, and delete webhooks that push events to a registered URL.
List and read the events that have happened in an organization, such as messages created or memberships changed, on a compliance officer token.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagesList, read, create, edit, and delete messages in a space or direct conversation, including text, rich text, and file attachments.6 | ||||||
| GET | /messages | List messages in a space, optionally filtered to those mentioning a person or before a date. | read | spark:messages_read | Current | |
A bot only sees messages in spaces it belongs to, and in a group space only messages that mention the bot. Acts onmessage Permission (capability) spark:messages_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /messages/direct | List the direct, one-to-one messages between the caller and a given person. | read | spark:messages_read | Current | |
Identifies the other person by personId or personEmail. Acts onmessage Permission (capability) spark:messages_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /messages/{messageId} | Get the details of a single message by its id. | read | spark:messages_read | Current | |
Returns the text, markdown, files, and the sender. Acts onmessage Permission (capability) spark:messages_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /messages | Post a message to a space or a person, as plain text or markdown, with up to one file attachment. | write | spark:messages_write | Current | |
Targets a roomId for a space or a toPersonId or toPersonEmail for a direct message. File previews render for attachments of 1MB or less. Acts onmessage Permission (capability) spark:messages_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /messages/{messageId} | Edit the text or markdown of a message the caller sent. | write | spark:messages_write | Current | |
Only a message's own author can edit it, and a file attachment cannot be changed by an edit. Acts onmessage Permission (capability) spark:messages_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /messages/{messageId} | Delete a message by its id. | write | spark:messages_write | Current | |
A user can delete their own messages, and a space moderator can delete anyone's. Acts onmessage Permission (capability) spark:messages_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SpacesList, read, create, update, and delete spaces, the group and direct conversations that hold messages and people.5 | ||||||
| GET | /rooms | List the spaces the caller belongs to. | read | spark:rooms_read | Current | |
Can be filtered to group spaces, direct spaces, or the spaces within a team. Acts onspace Permission (capability) spark:rooms_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rooms/{roomId} | Get the details of a single space. | read | spark:rooms_read | Current | |
Returns the title, type, team, and creation time. Acts onspace Permission (capability) spark:rooms_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rooms | Create a group space, optionally inside a team. | write | spark:rooms_write | Current | |
The caller becomes a member and moderator of the new space. Acts onspace Permission (capability) spark:rooms_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /rooms/{roomId} | Update a space, such as its title. | write | spark:rooms_write | Current | |
A direct space cannot be renamed. Acts onspace Permission (capability) spark:rooms_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /rooms/{roomId} | Delete a space and remove all of its members. | write | spark:rooms_write | Current | |
Deleting a space is permanent and removes its message history for everyone. Acts onspace Permission (capability) spark:rooms_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MembershipsList, read, create, update, and delete memberships, the link between a person and a space, which is how people are added to or removed from a conversation.4 | ||||||
| GET | /memberships | List the memberships of a space, the people in it and their roles. | read | spark:memberships_read | Current | |
Can be filtered by roomId, or by personId or personEmail across spaces. Acts onmembership Permission (capability) spark:memberships_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /memberships | Add a person to a space, optionally as a moderator. | write | spark:memberships_write | Current | |
Identifies the person by personId or personEmail. Adding someone to a space gives them its message history. Acts onmembership Permission (capability) spark:memberships_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /memberships/{membershipId} | Update a membership, such as promoting a person to moderator or demoting them. | write | spark:memberships_write | Current | |
The isModerator field controls the role. Acts onmembership Permission (capability) spark:memberships_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /memberships/{membershipId} | Remove a person from a space. | write | spark:memberships_write | Current | |
The person loses access to the space and its history. Acts onmembership Permission (capability) spark:memberships_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PeopleRead the calling user's own details, look up and list people, and on an admin token create, update, and delete people in the organization.4 | ||||||
| GET | /people/me | Get the profile of the person the token authenticates as. | read | spark:people_read | Current | |
Returns the caller's own display name, emails, and id. Acts onperson Permission (capability) spark:people_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /people | List people in the organization, filtered by email, display name, or id. | read | spark:people_read | Current | |
Returns people's email addresses and display names. A search filter such as email or displayName is required. Acts onperson Permission (capability) spark:people_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /people/{personId} | Get the details of a single person by their id. | read | spark:people_read | Current | |
Returns the person's email addresses and display name. Acts onperson Permission (capability) spark:people_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /people | Create a new person in the organization. | write | spark:people_write | Current | |
Requires an administrator token. Creating people is restricted to an organization administrator. Acts onperson Permission (capability) spark:people_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsList, read, create, update, and delete teams, the grouping that ties related spaces together.2 | ||||||
| GET | /teams | List the teams the caller belongs to. | read | spark:teams_read | Current | |
Returns each team's name and creation time. Acts onteam Permission (capability) spark:teams_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /teams | Create a team and a primary space within it. | write | spark:teams_write | Current | |
The caller becomes the team's first member and moderator. Acts onteam Permission (capability) spark:teams_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Team membershipsList, read, create, update, and delete the memberships that place people in a team.3 | ||||||
| GET | /team/memberships | List the people in a team. | read | spark:team_memberships_read | Current | |
Filtered by teamId. Acts onteam membership Permission (capability) spark:team_memberships_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /team/memberships | Add a person to a team, optionally as a moderator. | write | spark:team_memberships_write | Current | |
Adding someone to a team gives them access to its spaces. Acts onteam membership Permission (capability) spark:team_memberships_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /team/memberships/{membershipId} | Remove a person from a team. | write | spark:team_memberships_write | Current | |
The person loses access to the team's spaces. Acts onteam membership Permission (capability) spark:team_memberships_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MeetingsList, read, create, update, and delete scheduled meetings, and end a meeting that is running.5 | ||||||
| GET | /meetings | List scheduled meetings the caller hosts or is invited to. | read | meeting:schedules_read | Current | |
An admin listing on behalf of others needs meeting:admin_schedule_read. Acts onmeeting Permission (capability) meeting:schedules_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /meetings/{meetingId} | Get the details of a single meeting, including its join links. | read | meeting:schedules_read | Current | |
Returns the start and end times, agenda, and host details. Acts onmeeting Permission (capability) meeting:schedules_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /meetings | Schedule a meeting with a title, start and end time, and invitees. | write | meeting:schedules_write | Current | |
Scheduling on behalf of another host needs meeting:admin_schedule_write. Acts onmeeting Permission (capability) meeting:schedules_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /meetings/{meetingId} | Update a scheduled meeting, such as its time or invitees. | write | meeting:schedules_write | Current | |
A PATCH variant updates only the supplied fields. Acts onmeeting Permission (capability) meeting:schedules_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /meetings/{meetingId} | Cancel a scheduled meeting. | write | meeting:schedules_write | Current | |
Cancelling a meeting can notify the invitees by email. Acts onmeeting Permission (capability) meeting:schedules_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, update, and delete webhooks that push events to a registered URL.3 | ||||||
| GET | /webhooks | List the webhooks the caller has created. | read | — | Current | |
No extra scope beyond the token that created the webhooks. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Create a webhook that posts a chosen resource and event to a target URL. | write | — | Current | |
Creating a webhook for a resource needs the read scope for that resource, such as spark:messages_read for the messages resource. A secret signs each delivery. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/{webhookId} | Delete a webhook so it stops receiving events. | write | — | Current | |
Webex also disables a webhook automatically after repeated delivery failures. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsList and read the events that have happened in an organization, such as messages created or memberships changed, on a compliance officer token.1 | ||||||
| GET | /events | List events across the organization, such as messages created or memberships changed, on a compliance officer token. | read | spark-compliance:events_read | Current | |
Restricted to a compliance officer in the organization, and can return the content of messages across all spaces. Acts onevent Permission (capability) spark-compliance:events_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webex can notify an app or AI agent when something happens in a space, like a message being posted, a person joining, or a meeting starting. Webex posts the event to a webhook URL that has been registered for a chosen resource and event, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
messages / created | Fires when a message is posted to a space the webhook covers, including a direct message or a mention of a bot. | In-app only |
messages / deleted | Fires when a message is deleted. | In-app only |
memberships / created | Fires when a person is added to a space. | In-app only |
memberships / updated | Fires when a membership changes, such as a person being promoted to or demoted from moderator. | In-app only |
memberships / deleted | Fires when a person is removed from a space. | In-app only |
rooms / created | Fires when a space is created. | In-app only |
rooms / updated | Fires when a space is updated, such as a title change. | In-app only |
attachmentActions / created | Fires when a person submits a card the bot posted, such as a form built with Buttons and Cards. | In-app only |
meetings / started | Fires when a meeting starts. | In-app only |
meetings / ended | Fires when a meeting ends. | In-app only |
Webex limits how fast an app or AI agent can call, with a per-endpoint ceiling of roughly 300 requests per minute that the messages and people methods raise dynamically, and a bot's limits are less restrictive than an end user's.
Webex meters requests per endpoint rather than across the whole token. Most REST methods allow roughly 300 requests per minute, while the messages and people methods carry a higher quota that Webex adjusts dynamically. A bot account has less restrictive limits than an end-user account, and because limits are shared per user, a large workload is best partitioned across separate users running concurrent tasks. Going over returns 429 Too Many Requests with a Retry-After header that gives the number of seconds to wait before calling the same endpoint again.
List methods return up to a max number of items set by the max query parameter, and a Link response header carries the next URL when more results exist. The next link should be followed rather than built by hand, since it encodes the cursor for the following page.
Requests and responses are JSON. A message may carry one file attachment, and file previews render for attachments of 1MB or less. Each response includes a trackingId header that identifies the request in Webex's logs.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, such as a missing required field or an invalid value. The response body holds a message and a trackingId. | Read the message, correct the named field, and resend. |
| 401 | Unauthorized | The access token is missing, invalid, or expired. | Send a valid Bearer token, refreshing the OAuth token if it has expired. |
| 403 | Forbidden | The token is valid but lacks the scope or role for the call, such as posting to a space the caller is not a member of. | Grant the missing scope, or add the identity to the space, then retry. |
| 404 | Not Found | The resource does not exist, or the token cannot see it. Webex returns 404 rather than 403 so it does not confirm a hidden resource exists. | Confirm the id is correct and the token has access to the resource. |
| 429 | Too Many Requests | A per-endpoint rate limit was exceeded. The response carries a Retry-After header with the number of seconds to wait. | Wait the number of seconds in the Retry-After header before retrying the same endpoint. |
| 502 | Bad Gateway | A transient upstream error inside the Webex platform. | Retry after a short delay with backoff, and use the trackingId when contacting support. |
Webex serves a single current version of its REST API, version 1, and ships dated changes through a developer changelog rather than minting new version numbers.
The Webex REST API serves one current version, version 1, and ships changes through a dated developer changelog rather than minting new version numbers. Recent dated changes include new Query Recordings methods that replace the older List Recordings methods, meeting summary methods, and rate-limit and pagination changes that took effect on 31 October 2025.
Before these entries, the Webex REST API shipped a continuous stream of dated additions and deprecations through the changelog, such as the /events API gaining direct and breakout session messages, while keeping the version-1 surface stable for existing integrations.
An integration tracks the changelog for new methods, scope changes, and deprecations.
Webex API changelog ↗Bollard AI sits between a team's AI agents and Webex. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.