@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api VictorOps API
@base https://api.victorops.com/
@version 0.0.3
@auth ApiKey X-VO-Api-Key in header
@common_fields {X-VO-Api-Id: any # Your API ID, X-VO-Api-Key: any # Your API Key}
@endpoints 96
@hint download_for_search
@toc api-public(94), api-reporting(2)

@group api-public
@endpoint POST /api-public/v1/user
@desc Add a user
@required {body: any}
@returns(200) Some details about the user that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 409: The requested username or email address is not available, 422, 500: Internal Server Error}

@endpoint GET /api-public/v1/user
@desc List users
@returns(200) A list of users for your organization
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 422: You have reached your user limit, 500: Internal Server Error}

@endpoint GET /api-public/v2/user
@desc List users
@optional {email: any # An email address with which to search for users}
@returns(200) A list of the users in your organization. If the `email` parameter is present, the response is the list of users in your organization with a matching email address.
@errors {400: Problem with the request arguments. The `email` request parameter must be at least three (3) characters long, if present., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/user/batch
@desc Add multiple users
@optional {users: [any]}
@returns(200) The users were added, for errors, please see the response body
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 409: The requested username or email address is not available, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}
@desc Retrieve information for a user
@required {user: any # The VictorOps user to fetch}
@returns(200) Some details about the user that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 422: Username or email is unavailable, or you have reached your user limit., 500: Internal Server Error}

@endpoint PUT /api-public/v1/user/{user}
@desc Update a user
@required {user: any # The VictorOps user to be updated, body: map}
@returns(200) Some details about the user that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 409: The requested username or email address is not available, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint DELETE /api-public/v1/user/{user}
@desc Remove a user
@required {user: any # The VictorOps user to be deleted, body: map}
@returns(200) User was deleted
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 422: There was a problem with the delete such as a replacement is required or the replacement user was not found. Details will be provided in the response body., 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/teams
@desc Retrieve the user's team membership
@required {user: any # The VictorOps user}
@returns(200) Team details
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/policies/types/notifications
@desc Get the available notification types
@returns(200) All the available contact types
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/policies/types/contacts
@desc Get the available contact types
@returns(200) All the available contact types
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/policies/types/timeouts
@desc Get the available timeout values
@returns(200) All the available timeout types.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/profile/{username}/policies
@desc Get the user's primary paging policy
@required {username: any # Your username}
@returns(200) All steps of the user's paging policy
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint POST /api-public/v1/profile/{username}/policies
@desc Create a paging policy step
@required {username: any # Your username, body: map}
@returns(200) The created paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/profile/{username}/policies/{step}
@desc Get a paging policy step
@required {username: any # Your username, step: any # Paging policy step}
@returns(200) The paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint PUT /api-public/v1/profile/{username}/policies/{step}
@desc Update a paging policy step
@required {username: any # Your username, step: any # Paging policy step, body: map}
@returns(200) The updated paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint POST /api-public/v1/profile/{username}/policies/{step}
@desc Create a rule for a paging policy step
@required {username: any # Your username, step: any # Paging policy step, body: map}
@returns(200) The created rule for the paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/profile/{username}/policies/{step}/{rule}
@desc Get a rule from a paging policy step
@required {username: any # Your username, step: any # Paging policy step, rule: any # Rule for a paging policy step}
@returns(200) The rule from the paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint PUT /api-public/v1/profile/{username}/policies/{step}/{rule}
@desc Update a rule for a paging policy step
@required {username: any # Your username, step: any # Paging policy step, rule: any # Rule for a paging policy step, body: map}
@returns(200) The updated rule for the paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/profile/{username}/policies/{step}/{rule}
@desc Delete a rule from a paging policy step
@required {username: any # Your username, step: any # Paging policy step, rule: any # Rule for a paging policy step}
@returns(200) The deleted rule from the paging policy step
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v2/profile/{username}/policies
@desc Get the user's paging policies
@required {username: any # Your username}
@returns(200) All steps of the user's paging policy
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods
@desc Get a list of all contact methods for a user
@required {user: any # The VictorOps user ID}
@returns(200) All available contact methods for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/devices
@desc Get a list of all contact devices for a user
@required {user: any # The VictorOps user ID}
@returns(200) The list of contact devices for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/devices/{contactId}
@desc Get the indicated contact device for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) The list of contact devices for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint PUT /api-public/v1/user/{user}/contact-methods/devices/{contactId}
@desc Update a contact device for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier, body: map # The contact device}
@returns(200) The list of contact devices for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/user/{user}/contact-methods/devices/{contactId}
@desc Delete a contact device for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) Deleted contact device for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/emails
@desc Get a list of all contact emails for a user
@required {user: any # The VictorOps user ID}
@returns(200) The list of contact emails for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/user/{user}/contact-methods/emails
@desc Create a contact emails for a user
@required {user: any # The VictorOps user ID, body: map # The contact email}
@returns(200) The list of contact emails for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/emails/{contactId}
@desc Get the indicated contact email for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) The indicated contact email for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/user/{user}/contact-methods/emails/{contactId}
@desc Delete a contact email for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) Deleted contact email for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/phones
@desc Get a list of all contact phones for a user
@required {user: any # The VictorOps user ID}
@returns(200) The list of contact phones for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/user/{user}/contact-methods/phones
@desc Create a contact phones for a user
@required {user: any # The VictorOps user ID, body: map # The contact phone}
@returns(200) The list of contact phones for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/contact-methods/phones/{contactId}
@desc Get the indicated contact phone for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) The indicated contact phone for the user
@errors {401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/user/{user}/contact-methods/phones/{contactId}
@desc Delete a contact phone for a user
@required {user: any # The VictorOps user ID, contactId: any # The unique contact identifier}
@returns(200) Deleted contact phone for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/policies
@desc Get a list of paging policies for a user
@required {user: any # The VictorOps user ID}
@returns(200) All configured paging policies for a user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/user/{user}/oncall/schedule
@desc Get a user's on-call schedule
@required {user: any # The VictorOps user ID}
@optional {daysForward: any # Days to include in returned schedule (123 max), daysSkip: any # Days to skip before computing schedule to return (90 max), step: any # Step of escalation policy (3 max)}
@returns(200) The on-call schedule for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v2/user/{user}/oncall/schedule
@desc Get a user's on-call schedule
@required {user: any # The VictorOps user ID}
@optional {daysForward: any # Days to include in returned schedule (123 max), daysSkip: any # Days to skip before computing schedule to return (90 max), step: any # Step of escalation policy (3 max)}
@returns(200) The on-call schedule for the user
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/team/{team}/oncall/schedule
@desc Get a team's on-call schedule
@required {team: any # The VictorOps team 'slug'}
@optional {daysForward: any # Days to include in returned schedule (123 max), daysSkip: any # Days to skip before computing schedule to return (90 max), step: any # Step of escalation policy (3 max)}
@returns(200) The on-call schedule for the team
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 500: Internal Server Error}

@endpoint GET /api-public/v2/team/{team}/oncall/schedule
@desc Get a team's on-call schedule
@required {team: any # The VictorOps team 'slug'}
@optional {daysForward: any # Days to include in returned schedule (123 max), daysSkip: any # Days to skip before computing schedule to return (90 max), step: any # Step of escalation policy (3 max)}
@returns(200) The on-call schedule for the team
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 429: Rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/oncall/current
@desc Get an organization's on-call users
@returns(200) All users and escalation policies currently on call
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endgroup

@group api-reporting
@endpoint GET /api-reporting/v1/team/{team}/oncall/log
@desc A list of shift changes for a team
@required {team: any # The VictorOps team 'slug'}
@optional {start: any # Return shift changes occurring after this timestamp. The default is the start of the day at midnight. Specify the timestamp in ISO8601 format, end: any # Return shift changes occurring before this timestamp. The default is the end of the day at 11:59:59. Specify the timestamp in ISO8601 format, userName: any # The VictorOps user ID. Return shift changes occurring during the interval specified for this user. Without this parameter, all relevant users (with respect to the specified interval) are returned}
@returns(200) The result of the take request
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team or user(s) not found, 500: Internal Server Error}

@endgroup

@group api-public
@endpoint PATCH /api-public/v1/team/{team}/oncall/user
@desc Create an on-call override (take on-call)
@required {body: map # The take on-call payload, team: any # The VictorOps team 'slug'}
@returns(200) The result of the take request
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team or user(s) not found, 500: Internal Server Error}

@endpoint PATCH /api-public/v1/policies/{policy}/oncall/user
@desc Create an on-call override (take on-call)
@required {body: map # The take on-call payload, policy: any # The VictorOps policy 'slug'}
@returns(200) The result of the take request
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team or user(s) not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/incidents/{incidentNumber}
@desc Get a single incident
@required {incidentNumber: any # The Victorops incident number}
@returns(200) A single incident matching the provided incident number
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/incidents
@desc Get current incident information
@returns(200) The set of incidents.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/incidents
@desc Create a new incident
@required {body: map # The incident details}
@returns(200) Information about the incident created
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint PATCH /api-public/v1/incidents/ack
@desc Acknowledge an incident or list of incidents
@required {body: map # Ack/Resolve payload}
@returns(200) The result of each acknowledge incident action.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/incidents/reroute
@desc Reroute one or more incidents to one or more new routable destinations.
@required {body: map # The reroute rules}
@returns(200) The created reroute object

@endpoint PATCH /api-public/v1/incidents/resolve
@desc Resolve an incident or list of incidents
@required {body: map # Ack/Resolve payload}
@returns(200) The result of each resolve incident action.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint PATCH /api-public/v1/incidents/byUser/ack
@desc Acknowledge all incidents for which a user was paged.
@required {body: map # Ack/Resolve payload}
@returns(200) The result of each acknowledge incident action.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint PATCH /api-public/v1/incidents/byUser/resolve
@desc Resolve all incidents for which a user was paged.
@required {body: map # Ack/Resolve payload}
@returns(200) The result of each resolve incident action.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/incidents/{incidentNumber}/notes
@desc Get the notes associated with an incident
@required {incidentNumber: any # The incident number}
@returns(200) The set of notes associated with the incidentNumber.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/incidents/{incidentNumber}/notes
@desc Create a new Note
@required {body: map, incidentNumber: any # The incident number}
@returns(200) Information about the note created
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint PUT /api-public/v1/incidents/{incidentNumber}/notes/{noteName}
@desc Update a Note
@required {body: map, incidentNumber: any # The incident number, noteName: any # The html encoded name field of the note}
@returns(200) Information about the note updated
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/incidents/{incidentNumber}/notes/{noteName}
@desc Delete a Note
@required {incidentNumber: any # The incident number, noteName: any # The html encoded name field of the note}
@returns(200) Whether the note was successfully deleted
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/alerts/{uuid}
@desc Retrieve alert details.
@required {uuid: any # The VictorOps uuid of the alert}
@returns(200) The alert, if found.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/org/routing-keys
@desc List routing keys with associated teams
@returns(200) The list of routing keys and associated teams
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/org/routing-keys
@desc Create a new routing key
@required {body: map}
@returns(200) The created routing-key
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/overrides
@desc List the scheduled overrides
@returns(200) A list of scheduled overrides for your organization
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint POST /api-public/v1/overrides
@desc Creates a new scheduled override
@required {body: map}
@returns(200) The created scheduled override
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/overrides/{publicId}
@desc Get the specified scheduled override
@required {publicId: any # The publicId of the scheduled override}
@returns(200) The scheduled override
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint DELETE /api-public/v1/overrides/{publicId}
@desc Deletes a scheduled override
@required {publicId: any # The publicId of the scheduled override}
@returns(200) Whether or not the delete was successful
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/overrides/{publicId}/assignments
@desc Get the specified scheduled override
@required {publicId: any # The publicId of the scheduled override}
@returns(200) The assignments for a given scheduled override
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/overrides/{publicId}/assignments/{policySlug}
@desc Get the specified scheduled override assignment
@required {publicId: any # The publicId of the scheduled override, policySlug: any # The policySlug of the assignment}
@returns(200) The assignment for the given publicId
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint PUT /api-public/v1/overrides/{publicId}/assignments/{policySlug}
@desc Update the scheduled override assignment
@required {publicId: any # The publicId of the scheduled override, policySlug: any # The policySlug of the assignment, body: map # The policy and username we are assigning}
@returns(200) The assignment for the given policySlug
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint DELETE /api-public/v1/overrides/{publicId}/assignments/{policySlug}
@desc Delete the scheduled override assignment
@required {publicId: any # The publicId of the scheduled override, policySlug: any # The policySlug of the assignment}
@returns(200) The assignment that was deleted for the given scheduled override and policySlug
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 422: You have reached your user limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/teams/{team}/rotations
@desc Get all rotation groups for a team
@required {team: any # The uniquely identifying team slug for which to retrieve rotation groups}
@returns(200) An object containing a list of all rotation groups that exist under the provided team A rotation is one rotation and all of its shifts. This is represented in the UI as a single rotation.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/teams/{team}/rotations
@desc Create a rotation group
@required {team: any # The team slug, body: map}
@optional {skip: any # Number of weeks to skip for the on-call period preview, count: any # Number of weeks to show for the on-call period preview}
@returns(200) The created rotation group with its shifts and on-call period details
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/teams/{team}/rotations/{groupId}
@desc Delete a rotation group
@required {team: any # The team slug, groupId: any # The rotation group ID}
@returns(200) The rotation group was successfully deleted
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/teams/{team}/rotations/{groupId}/{shiftId}/scheduled
@desc Get the scheduled user for a shift
@required {team: any # The team slug, groupId: any # The rotation group ID, shiftId: any # The rotation shift ID}
@returns(200) The currently scheduled user for the specified shift
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint PUT /api-public/v1/teams/{team}/rotations/{groupId}/{shiftId}/scheduled
@desc Set the scheduled user for a shift
@required {team: any # The team slug, groupId: any # The rotation group ID, shiftId: any # The rotation shift ID, body: map}
@returns(200) The scheduled user after the update
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v2/team/{team}/rotations
@desc Get all rotations and some rotation details for a team
@required {team: any # The uniquely identifying team slug for which to retrieve rotations}
@returns(200) An object containing a list of all rotations that exist under the provided team
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/webhooks
@desc Get all of your organization's webhooks
@returns(200) An object containing a list of all webhooks existing in the organization This references the webhooks created in the "Webhooks" integration.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/policies
@desc Get a list of escalation policy info
@optional {filter: any # An escalation policy name to be used for filtering the results. Note: If this parameter is present, it must be at least three (3) characters long}
@returns(200) A list of escalation policy info objects, each of which contain a summary of an escalation policy and a summary for the team associated with that escalation policy.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/policies
@desc Create an escalation policy
@required {body: map # The request body needed to create an escalation policy}
@returns(200) The newly created escalation policy
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/policies/{policy}
@desc Get a specific escalation policy
@required {policy: any # The uniquely identifying escalation policy slug.  Thus slug is in the format `pol-[\w\d]{16}`}
@returns(200) The escalation policy matching the provided slug
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/policies/{policy}
@desc Delete a specified escalation policy
@required {policy: any # The uniquely identifying escalation policy slug. The policy slug is in the format `pol-[\w\d]{16}`}
@returns(200) The escalation policy was deleted
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endgroup

@group api-reporting
@endpoint GET /api-reporting/v2/incidents
@desc Get/search incident history
@optional {offset: any # The offset within the set of matching incidents, limit: any # The maximum number of matching incidents to return (100 max), entityId: any # The entity ID involved  This is the unique identifier for the entity causing the incident., incidentNumber: any # The incident number as shown in VictorOps Multiple values and ranges are allowed: 4,5,20:50, startedAfter: any # Return incidents started after this timestamp Specify the timestamp in ISO8601 format, startedBefore: any # Find incidents started before this timestamp  Specify the timestamp in ISO8601 format, host: any # The host involved in the incident Multiple values can be separated with commas., service: any # The service involved in the incident (if any) Multiple values can be separated with commas., currentPhase: any # The current phase of the incident "resolved", "triggered" or "acknowledged". Multiple values can be separated with commas. By default, response contains only "resolved" incidents, routingKey: any # The original routing of the incident}
@returns(200) The list of incidents matching the request filters
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 500: Internal Server Error}

@endgroup

@group api-public
@endpoint POST /api-public/v1/team
@desc Add a team
@required {body: map # The team information}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/team
@desc List teams
@returns(200) A list of teams for your organization
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: You have reached your team limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/team/{team}
@desc Retrieve information for a team
@required {team: any # The VictorOps team to fetch}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint PUT /api-public/v1/team/{team}
@desc Update a team
@required {team: any # The VictorOps team to be updated, body: map # The team information}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint DELETE /api-public/v1/team/{team}
@desc Remove a team
@required {team: any # The VictorOps team to be deleted}
@returns(200) Team was deleted
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: There was a problem with the delete such as the replacement team was not found., 500: Internal Server Error}

@endpoint GET /api-public/v1/team/{team}/policies
@desc Retrieve a list of escalation policies for a team
@required {team: any # The VictorOps team to fetch}
@returns(200) The escalation policy list. This does not include details about the actual notification steps of the policy.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint GET /api-public/v1/team/{team}/admins
@desc Retrieve a list of team admins for a team
@required {team: any # The VictorOps team}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 500: Internal Server Error}

@endpoint GET /api-public/v1/team/{team}/members
@desc Retrieve a list of members for a team
@required {team: any # The VictorOps team to fetch}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint POST /api-public/v1/team/{team}/members
@desc Add a team member
@required {team: any # The VictorOps team to fetch, body: map}
@returns(200) Some details about the team that was added
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: Team name or email is unavailable, or you have reached your team limit., 500: Internal Server Error}

@endpoint DELETE /api-public/v1/team/{team}/members/{user}
@desc Remove a team member
@required {team: any # The VictorOps team to be removed from, user: any # The team member username to be removed, body: map # The user information}
@returns(200) User was successfully removed from team
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Team not found, 422: There was a problem with the delete such as the replacement team member was not found., 500: Internal Server Error}

@endpoint GET /api-public/v1/maintenancemode
@desc Get an organization's current maintenance mode state
@returns(200) maintenance mode state
@errors {403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint POST /api-public/v1/maintenancemode/start
@desc Start maintenance mode for routing keys
@required {body: map # the definition of the maintenance mode you want to start}
@returns(200) maintenance mode state
@errors {403: Authentication failed or rate-limit reached, 409: You have an active global maintanance mode and are attempting to start a second. You may only have a single Global maintenance mode at a time, 420: You have reached the limit of allowed active maintenance modes, 500: Internal Server Error}

@endpoint PUT /api-public/v1/maintenancemode/{maintenancemodeid}/end
@desc End maintenance mode for routing keys
@required {maintenancemodeid: any # The id of the maintenance mode found in the active maintenance mode object}
@returns(200) maintenance mode state
@errors {403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint POST /api-public/v1/chat
@desc Send a chat message into VictorOps
@required {body: map}
@returns(200) A chat message was successfully created.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint POST /api-public/v1/stakeholders/sendMessage
@desc Sends a stakeholder message to the recipients. Recipients can either be User/team or both.
@required {body: map # The request body needed to send Stakeholder message.}
@returns(200) Status success.
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: Path not found, 429: Rate-limit reached, 500: Internal Server Error}

@endpoint GET /api-public/v1/alertRules
@desc Get all alert rules
@returns(200) The alert rules of an organization
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 500: Internal Server Error}

@endpoint POST /api-public/v1/alertRules
@desc Create alert rule
@required {body: map # The request body needed to create/update an alert rule with annotations}
@returns(200) The created alert rule
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint PUT /api-public/v1/alertRules/{ruleId}
@desc Update alert rule
@required {body: map # The request body needed to create/update an alert rule with annotations, ruleId: any # Alert rule id}
@returns(200) The updated alert rule
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endpoint DELETE /api-public/v1/alertRules/{ruleId}
@desc Delete alert rule
@required {ruleId: any # Alert rule id}
@returns(200) The deleted alert rule id
@errors {400: Problem with the request arguments.  The response payload may include an error message., 401: Authentication parameters missing, 403: Authentication failed or rate-limit reached, 404: User not found, 500: Internal Server Error}

@endgroup

@end