Source
API documentation — xMatters
Checked for xMatters on 6 Nov 2026
- Page
- https://help.xmatters.com/xmapi/
- Checked
- 6 Nov 2026, 04:53 UTC
- How we may use it
- Public page, crawling permitted
Technical details
- type
- page
- http status
- 200
- content hash
- sha256:d35bccb53755fee9f29d29f07a1b1b7ea7b8f5c755bd767239637d1a0b48a31e
- permission
- robots_ok
- screenshot
- Screenshot on file (internal exhibit, not published)
Cited by
Facts read from this source
-
Rest API overview Report an error
“The xMatters REST API allows you to interact with xMatters using RESTful requests over the HTTP protocol.”
-
API version Report an error
“The version of xMatters REST API is included as part of the base URL. This API is currently on version 1.”
-
Base URL format Report an error
“https://<company>.<deployment>.xmatters.com/api/xm/<version>/”
-
Authentication Report an error
“The xMatters REST API supports HTTP Basic authentication and OAuth authentication.”
-
API key auth Report an error
“You can authenticate requests with the same web login ID and password that you use to log on natively to the xMatters web user interface, or use an API key and secret to authenticate. To use an API key as your username, it must be prepended with x-api-key-.”
-
Https required Report an error
“Regardless of which authentication method you use, ensure that you use HTTPS when making RESTful requests so that sensitive information such as passwords and tokens are secured during transmission.”
-
Role rest web service user Report an error
“The REST Web Service User role provides the required permissions for accessing some of the most commonly-used xMatters endpoints and provides permission to create and update all users and groups.”
-
Forbidden response Report an error
“When the authenticating user does not have permission to access an endpoint, they receive a "403: Forbidden" response.”
-
Historical access permission Report an error
“To query historical data, the authenticating REST API user must have the ability.act.HistoricalDataAccess permission added to a function within their roles.”
-
Runtime retention Report an error
“While runtime data is available for 30 days, historical data is available to the point in time supported by your pricing plan.”
-
Sync window Report an error
“To allow for unknown factors such as clock drift and network lag, there is a 15-minute synchronization window between data collected by the current system and the contents of the extended data retention facility.”
-
Http methods Report an error
“The xMatters REST API supports the following HTTP methods: GET Returns a description of a resource. POST Creates or updates a resource. DELETE Deletes a resource.”
-
Request formats Report an error
“xMatters accepts request data in JSON and form-data formats.”
-
Response format Report an error
“Responses from the xMatters REST API are in JSON format.”
-
Charset Report an error
“To avoid errors in parsing request data, always use UTF-8 character encoding.”
-
Pagination limit max Report an error
“Additionally, you can retrieve any subset of the result set by specifying values for the offset and limit query parameters. The maximum value of the limit parameter is 1000.”
-
Resource identification Report an error
“This API provides two ways of identifying resources: by unique identifier (stored in the id field) by name (stored in the targetName field)”
-
Media types json only Report an error
“406 Not acceptable The requested media type is not supported. This API supports application/JSON only.”
-
Rate limiting Report an error
“429 Too many requests The request cannot be processed because the request rate limit has been exceeded.”
-
Oauth tokens revocable Report an error
“OAuth authentication authorizes requests by passing a token in the header of each request. This enables you to avoid storing a user name and password in your application. Tokens can be revoked at any time.”
-
Js library xmtoolbox Report an error
“xmtoolbox is a JavaScript package that simplifies interaction with xMatters. By providing a wrapper to documented xMatters APIs, xmtoolbox makes backup/restoration and user/group synchronization easy.”
-
Events renamed alerts UI Report an error
“While we've renamed "events" to "alerts" in the web user interface, we are not changing any of the properties, values, or labels associated with events in the REST API.”
-
Plans renamed workflows Report an error
“We've renamed "communication plans" to "workflows" and are working to update the xMatters REST API guide to reflect those changes.”
-
Endpoint objects Report an error
“ALERTS ATTACHMENTS AUDITS CHANGE INTELLIGENCE DEVICES DEVICE NAMES DEVICE TYPES DYNAMIC TEAMS EVENTS EVENT SUPPRESSIONS EXTERNAL CONFERENCE BRIDGES FORMS GROUP MEMBERS GROUPS IMPORT JOBS INCIDENTS INTEGRATIONS OAUTH ON-CALL ON-CALL SUMMARY PEOPLE PLANS PLAN CONSTANTS PLAN ENDPOINTS PLAN PROPERTIES ROLES SCENARIOS SCHEDULED MESSAGES SERVICE DEPENDENCIES SERVICES SHARED LIBRARIES SHIFTS SIGNALS SITES SUBSCRIPTION FORMS SUBSCRIPTIONS TEMPORARY ABSENCES UPLOAD USERS”
-
Attachments max file size Report an error
“Uploads a file to xMatters for use as an attachment with existing events and scenarios. Each file has a maximum file size of 10 MB each.”
-
Attachments upload irreversible Report an error
“Once a file is uploaded to xMatters it cannot be removed and should be attached to an event or scenario as quickly as possible. Unused files are automatcially discarded after a period of time.”
-
Audits endpoint Report an error
“You can use the /audits endpoint to access audit records.”
-
System audits endpoint Report an error
“Returns system audit report entries for the authenticated organization. The endpoint only returns data for the three days preceding the date of the request.”
-
Web service audits endpoint Report an error
“Returns web service audit report information for a specified time span for the authenticated organization. The span between the from and to dates cannot exceed the historical data access limit for your instance.”
-
Historical data plan dependent Report an error
“When setting the from parameter, the length of time you can set is limited by your pricing plan. Also the at timestamp cannot be earlier than the fromtimestamp.”
-
Upload users endpoint Report an error
“To upload files of user data, the supported content type is multipart/form-data.”
-
Externally owned field Report an error
“A field is externally owned when it is managed by an external system. Externally-owned objects cannot be deleted in the xMatters user interface by most users.”
-
External key field Report an error
“This field identifies a resource in an external system.”
-
Historical permission client services Report an error
“Currently, access to historical data is controlled by a single permission that is enabled or disabled by Client Services for specific user roles.”
3 facts read from this page are not shown because they could not be confirmed on the page as captured.
Scores citing this record
- The Engineering Manager On-call schedules, rotations & escalation
- The Engineering Manager Integrations, API & administration
- The Engineering Manager Platform reliability, security & compliance
- The ICT Risk Officer On-call schedules, rotations & escalation
- The ICT Risk Officer Integrations, API & administration
- The IT Operations Manager On-call schedules, rotations & escalation
- The IT Operations Manager Integrations, API & administration
- The IT Operations Manager Platform reliability, security & compliance
- The MSP NOC Lead Integrations, API & administration
- The Skeptic On-call schedules, rotations & escalation
- The Skeptic Integrations, API & administration
- The SRE Lead On-call schedules, rotations & escalation
- The SRE Lead Integrations, API & administration
- The SRE Lead Platform reliability, security & compliance