VictorOps API Client
The victorops-api-client
library contains a simple and convenient HTTP client for making requests to
the VictorOps REST API.
Table of contents
Installation
Using NPM:
$ npm install victorops-api-client
Using Yarn:
$ yarn add victorops-api-client
Usage
Initialize the client
The library exports a VictorOpsApiClient
class. All you need to do is instantiate it, and you're ready to go.
You'll need an API ID and API key provided by VictorOps. You can provide these values as apiId
and apiKey
options or set these values as environment variables using VO_API_ID
and VO_API_KEY
.
By default, the client will use the VO_API_ID
and VO_API_KEY
environment variables if apiId
and apiKey
are not provided in the options.
Example import methods:
const VictorOpsApiClient = require('victorops-api-client');
const client = new VictorOpsApiClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
import VictorOpsApiClient from 'victorops-api-client';
const client = new VictorOpsApiClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
It is required to set the API ID and API key parameters as either environment variables or as options when instantiating the client. These parameters are necessary to execute VictorOpsApiClient
calls. If these parameters are not provided or cannot be determined, then an error is thrown.
Using environment variables in an application:
const VictorOpsApiClient = require('victorops-api-client');
// Set the API ID and key as environment variables.
process.env.VO_API_ID = 'SOME-API-ID';
process.env.VO_API_KEY = 'SOME-API-KEY';
const client = new VictorOpsApiClient();
Setting environment variables before running an application:
Linux:
$ VO_API_ID=SOME-API-ID VO_API_KEY=SOME-API-KEY node app.js
Windows:
> cmd /C "set VO_API_ID=SOME-API-ID && set VO_API_KEY=SOME-API-KEY && node app.js"
Options
These are the available options for creating a VictorOpsApiClient
instance. If the apiId
and apiKey
options are not provided, then the VO_API_ID
and VO_API_KEY
environment variables will be used instead.
Name | Default | Description |
---|---|---|
apiId |
undefined |
VictorOps API ID |
apiKey |
undefined |
VictorOps API Key |
timeout |
5000 |
Number of milliseconds before the request times out |
baseUrl |
https://api.victorops.com |
The base URL for the VictorOps REST API |
fullResponse |
false |
Get the full response instead of just the body |
maxContentLength |
10000 |
The max size of the HTTP response content in bytes |
maxBodyLength |
2000 |
The max allowed size of the HTTP request body in bytes |
Examples
Create an instance:
const VictorOpsApiClient = require('victorops-api-client');
const client = new VictorOpsApiClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
Get a list of users:
async function getUsers() {
try {
const users = await client.users.getUsers();
return users;
} catch(err) {
console.error(err);
}
}
Get a list of incidents:
async function getIncidents() {
try {
const incidents = await client.incidents.getIncidents();
return incidents;
} catch(err) {
console.error(err);
}
}
Create a new incident:
async function createIncident() {
try {
const resp = await client.incidents.createIncident({
summary: 'Test incident',
details: 'Something bad happened!!!',
userName: 'johndoe',
targets: [
{
type: 'User',
slug: 'johndoe'
}
],
isMultiResponder: true
});
return resp;
} catch(err) {
console.error(err);
}
}
Get a list of teams:
async function getTeams() {
try {
const teams = await client.teams.getTeams();
return teams;
} catch(err) {
console.error(err);
}
}
Documentation
The client instance has a named property for each of the public endpoints in the VictorOps REST API. Each endpoint property contains methods that correspond to the operations associated with the endpoint (according to the VictorOps API). All named endpoint methods return a Promise
which resolves with the response data or rejects with an error. Below are the endpoints and operations included with the client.
Any endpoint operation that takes a query
argument expects the value to be an Object
that contains the query parameters for that particular endpoint operation. Please refer to the endpoint operation's documentation for the correct query parameters.
On-Call
-
client.oncall.getUserSchedule(user, query)
- Get a user's on-call schedule - VictorOps Documentation -
client.oncall.getTeamSchedule(team, query)
- Get a team's on-call schedule - VictorOps Documentation -
client.oncall.getOncallUsers()
- Get an organization's on-call users - VictorOps Documentation -
client.oncall.createOncallOverride(policy, takeOncall)
- Create an on-call override (take on-call) - VictorOps Documentation
Incidents
-
client.incidents.getIncidents()
- Get the current incident information - VictorOps Documentation -
client.incidents.createIncident(details)
- Creates a new incident - VictorOps Documentation -
client.incidents.ackIncidents(ackInfo)
- Acknowledge an incident or list of incidents - VictorOps Documentation -
client.incidents.rerouteIncidents(rules)
- Reroute one or more incidents - VictorOps Documentation -
client.incidents.resolveIncidents(resolveInfo)
- Resolve an incident or list of incidents - VictorOps Documentation -
client.incidents.ackUserIncidents(ackInfo)
- Acknowledge all incidents for which a user was paged - VictorOps Documentation -
client.incidents.resolveUserIncidents(resolveInfo)
- Resolve all incidents for which a user was paged - VictorOps Documentation
Alerts
-
client.alerts.getAlert(uuid)
- Get information about an alert - VictorOps Documentation
Reporting
-
client.reporting.getShiftChanges(team, query)
- Get a list of shift changes for a team - VictorOps Documentation -
client.reporting.getIncidentHistory(query)
- Get/search incident history - VictorOps Documentation
Users
-
client.users.getUsers()
- Get a list of users for an organization - VictorOps Documentation -
client.users.addUser(user)
- Add a user to an organization - VictorOps Documentation -
client.users.addUsers(users)
- Add users to an organization - VictorOps Documentation -
client.users.deleteUser(user, replacement)
- Remove a user from an organization - VictorOps Documentation -
client.users.getUser(user)
- Get the information for the specified user - VictorOps Documentation -
client.users.updateUser(user, userInfo)
- Update the designated user - VictorOps Documentation -
client.users.getTeams(user)
- Get the user's team membership - VictorOps Documentation
User Contact Methods
-
client.contactMethods.getContactMethods(user)
- Get a list of all contact methods for a user - VictorOps Documentation -
client.contactMethods.getContactDevices(user)
- Get a list of all contact devices for a user - VictorOps Documentation -
client.contactMethods.deleteContactDevice(user, contactId)
- Delete a contact device for a user - VictorOps Documentation -
client.contactMethods.getContactDevice(user, contactId)
- Get the indicated contact device for a user - VictorOps Documentation -
client.contactMethods.updateContactDevice(user, contactId, contactDevice)
- Update a contact device for a user - VictorOps Documentation -
client.contactMethods.getContactEmails(user)
- Get a list of all contact emails for a user - VictorOps Documentation -
client.contactMethods.createContactEmail(user, contactEmail)
- Create a contact email for a user - VictorOps Documentation -
client.contactMethods.deleteContactEmail(user, contactId)
- Delete a contact email for a user - VictorOps Documentation -
client.contactMethods.getContactEmail(user, contactId)
- Get a contact email for a user - VictorOps Documentation -
client.contactMethods.getContactPhones(user)
- Get a list of all contact phones for a user - VictorOps Documentation -
client.contactMethods.createContactPhone(user, contactPhone)
- Create a contact phone for a user - VictorOps Documentation -
client.contactMethods.deleteContactPhone(user, contactId)
- Delete a contact phone for a user - VictorOps Documentation -
client.contactMethods.getContactPhone(user, contactId)
- Get a contact phone for a user - VictorOps Documentation
User Paging Policies
-
client.userPagingPolicies.getPagingPolicies(user)
- Get paging policies for a user - VictorOps Documentation
Personal Paging Policy Values
-
client.pagingPolicyValues.getNotificationTypes()
- Get the available notification types - VictorOps Documentation -
client.pagingPolicyValues.getContactTypes()
- Get the available contact types - VictorOps Documentation -
client.pagingPolicyValues.getTimeoutValues()
- Get the available timeout values - VictorOps Documentation
Personal Paging Policies
-
client.personalPagingPolicies.getPagingPolicy(username)
- Get a user's paging policy - VictorOps Documentation -
client.personalPagingPolicies.createPolicyStep(username, stepInfo)
- Create a paging policy step - VictorOps Documentation -
client.personalPagingPolicies.getPolicyStep(username, step)
- Get a paging policy step - VictorOps Documentation -
client.personalPagingPolicies.createPolicyStepRule(username, step, ruleInfo)
- Creates a rule for a paging policy step. - VictorOps Documentation -
client.personalPagingPolicies.updatePolicyStep(username, step, stepInfo)
- Updates a paging policy step - VictorOps Documentation -
client.personalPagingPolicies.deletePolicyStepRule(username, step, rule)
- Deletes a rule for a paging policy step - VictorOps Documentation -
client.personalPagingPolicies.getPolicyStepRule(username, step, rule)
- Gets a rule for a paging policy step - VictorOps Documentation -
client.personalPagingPolicies.updatePolicyStepRule(username, step, rule, ruleInfo)
- Updates a rule for a paging policy step - VictorOps Documentation
Teams
-
client.teams.getTeams()
- Get a list of teams for your organization - VictorOps Documentation -
client.teams.addTeam(teamInfo)
- Add a team to your organization - VictorOps Documentation -
client.teams.removeTeam(team)
- Remove a team from your organization - VictorOps Documentation -
client.teams.getTeam(team)
- Get the information for the specified team - VictorOps Documentation -
client.teams.updateTeam(team, teamInfo)
- Update the information for the specified team - VictorOps Documentation -
client.teams.getAdmins(team)
- Get the team admins for the specified team - VictorOps Documentation -
client.teams.getMembers(team)
- Get the team members for the specified team - VictorOps Documentation -
client.teams.addMember(team, memberInfo)
- Add a team member to the specified team - VictorOps Documentation -
client.teams.removeMember(team, user, replacement)
- Remove a team member from the specified team - VictorOps Documentation
Escalation Policies
-
client.escalationPolicies.getPolicies()
- Get a list of escalation policy information - VictorOps Documentation -
client.escalationPolicies.createPolicy(policyInfo)
- Create an escalation policy - VictorOps Documentation -
client.escalationPolicies.deletePolicy(policy)
- Delete a specified escalation policy - VictorOps Documentation -
client.escalationPolicies.getPolicy(policy)
- Get a specific escalation policy - VictorOps Documentation
Routing Keys
-
client.routingKeys.getRoutingKeys()
- List routing keys and associated teams - VictorOps Documentation -
client.routingKeys.createRoutingKey(keyInfo)
- Create a new routing key with escalation policy mapping - VictorOps Documentation
Scheduled Overrides
-
client.scheduledOverrides.getOverrides()
- List all the scheduled overrides for an organization - VictorOps Documentation -
client.scheduledOverrides.createOverride(overrideInfo)
- Create a new scheduled override - VictorOps Documentation -
client.scheduledOverrides.deleteOverride(publicId)
- Deletes a scheduled override - VictorOps Documentation -
client.scheduledOverrides.getOverride(publicId)
- Get the specified scheduled override - VictorOps Documentation -
client.scheduledOverrides.getAssignments(publicId)
- Get the specified scheduled override assignments - VictorOps Documentation -
client.scheduledOverrides.deleteAssignment(publicId, policySlug)
- Delete a scheduled override assignment - VictorOps Documentation -
client.scheduledOverrides.getAssignment(publicId, policySlug)
- Get the specified scheduled override assignments - VictorOps Documentation -
client.scheduledOverrides.updateAssignment(publicId, policySlug, assignmentInfo)
- Update a scheduled override assignment - VictorOps Documentation
Rotations
-
client.rotations.getRotationGroups(team)
- Get a list of all rotation groups for a team - VictorOps Documentation
Webhooks
-
client.webhooks.getWebhooks()
- Get a list of all the webhooks for an organization - VictorOps Documentation
Chat
-
client.chat.sendChat(chatInfo)
- Send a chat message - VictorOps Documentation
Notes
-
client.notes.getNotes(incidentNumber)
- Get the notes associated with an incident - VictorOps Documentation -
client.notes.createNote(incidentNumber, noteInfo)
- Create a new note for an incident - VictorOps Documentation -
client.notes.deleteNote(incidentNumber, noteName)
- Delete a note - VictorOps Documentation -
client.notes.updateNote(incidentNumber, noteName, noteInfo)
- Update an existing note - VictorOps Documentation
Maintenance Mode
-
client.maintenanceMode.getModeState()
- Get an organization's current maintenance mode state - VictorOps Documentation -
client.maintenanceMode.startMode(modeDef)
- Start maintenance mode for routing keys - VictorOps Documentation -
client.maintenanceMode.endMode(modeId)
- End maintenance mode for routing keys - VictorOps Documentation
Change Log
The CHANGELOG contains descriptions of notable changes.
License
This software is licensed under the Apache 2 license.